How-To
Integrate with GitHub Actions

How to Integrate with GitHub Actions

This guide walks you through adding NAT to your GitHub Actions CI pipeline so that every pull request and deployment is automatically scanned for API security vulnerabilities.

Add your NAT API key as a GitHub secret

  1. Go to your repository on GitHub → Settings → Secrets and variables → Actions
  2. Click New repository secret
  3. Name: NAT_API_KEY, Value: your NAT API key
  4. Click Add secret

If your API requires authentication for testing, also add:

  • API_TOKEN — bearer token or API key for your staging API
  • Any other credentials needed (OAuth2 client secret, etc.)

Create the workflow file

Create .github/workflows/nat-scan.yml in your repository:

name: API Security Scan
 
on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]
 
jobs:
  nat-security-scan:
    name: NAT API Security Scan
    runs-on: ubuntu-latest
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Run NAT API Security Scan
        uses: bg-playground/nat-action@v1
        with:
          api-url: ${{ vars.STAGING_API_URL }}
          api-key: ${{ secrets.NAT_API_KEY }}
          spec: ./openapi.yaml
          auth-type: bearer
          token: ${{ secrets.API_TOKEN }}
          fail-on: high
          output-format: sarif
 
      - name: Upload to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()   # upload even if the scan found issues
        with:
          sarif_file: nat-results.sarif
          category: nat-api-security

Set the STAGING_API_URL variable

  1. Go to Settings → Secrets and variables → Actions → Variables tab
  2. Click New repository variable
  3. Name: STAGING_API_URL, Value: the URL of your staging API (e.g., https://staging.example.com)

Commit and push

git add .github/workflows/nat-scan.yml
git commit -m "Add NAT API security scan to CI"
git push

Open a pull request to trigger the workflow.

Review results

After the workflow runs:

  • In the PR — The check will appear as "NAT API Security Scan". A failing check means high or critical findings were discovered.
  • In Code Scanning — Go to Security → Code scanning to see all findings with their severity, description, and remediation.

Workflow for staging + production deployments

For teams that deploy to staging before production, here's a more complete workflow:

name: API Security Scan
 
on:
  pull_request:
    branches: [main]
  deployment_status:   # also run after deployment to staging
 
jobs:
  nat-security-scan:
    name: NAT API Security Scan
    runs-on: ubuntu-latest
    # Only run on staging environment deployments
    if: |
      github.event_name == 'pull_request' ||
      (github.event_name == 'deployment_status' &&
       github.event.deployment_status.state == 'success' &&
       github.event.deployment.environment == 'staging')
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Run NAT scan
        uses: bg-playground/nat-action@v1
        id: nat
        with:
          api-url: ${{ vars.STAGING_API_URL }}
          api-key: ${{ secrets.NAT_API_KEY }}
          spec: ./openapi.yaml
          auth-type: bearer
          token: ${{ secrets.STAGING_API_TOKEN }}
          fail-on: high
          output-format: sarif
 
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: nat-results.sarif
 
      - name: Comment on PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## NAT Security Scan Results\n\n` +
                    `Findings: ${{ steps.nat.outputs.finding-count }} total ` +
                    `(${{ steps.nat.outputs.critical-count }} critical, ` +
                    `${{ steps.nat.outputs.high-count }} high)\n\n` +
                    `[View full report](${{ steps.nat.outputs.report-url }})`
            })

Failing the build on findings

The fail-on input controls which severity level fails the build:

ValueEffect
criticalOnly fail on critical findings
highFail on high or critical (recommended)
mediumFail on medium, high, or critical
lowFail on any finding except informational
infoFail on any finding (very strict)
(omit)Never fail the build

Caching for faster runs

- name: Cache pip packages
  uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: nat-${{ runner.os }}-pip

Next steps

Set Up OAuth2Deploy with Docker