Nullgap.dev Docs

Developers

CI examples

Pipeline steps for GitHub Actions, GitLab CI, Bitbucket Pipelines and Azure Pipelines that use an API key to check packages, export findings, gate a pull request or a release and start a pentest.

Pull request review needs nothing in your pipeline: once a repository is connected, Nullgap reviews pull requests and reports a check on its own (see checks and gating). The steps on this page are for the other things a pipeline may want from Nullgap. The first four call the REST API with curl; the last section does the same work with the nullgap command, with recipes for GitHub Actions, GitLab CI, Bitbucket Pipelines and Azure Pipelines.

#Before you start

  1. Create an API key with the scope from the table. See API keys. Use a separate key for the pentest job, since it needs admin.
  2. Store it in your CI system's secret store, and set the other two values as ordinary variables:
NameValueGitHub ActionsGitLab CI
NULLGAP_API_KEYThe keyA repository or organisation secretA masked, protected CI/CD variable
NULLGAP_URLThe address of your Nullgap console, no trailing slashA variableA CI/CD variable
NULLGAP_ORGYour organisation's slugA variableA CI/CD variable

The steps need curl and jq. GitHub's hosted runners have both; the GitLab examples install them into a small image.

Two habits used in every example, and worth keeping in your own steps:

  • curl -fsS makes an HTTP error fail the step. Without -f, a 401 from an expired key would look like "no findings".
  • The answer is written to a file first and read with jq afterwards, so a failed request can never be mistaken for an empty result.

Errors, paging and rate limits are described in the API overview.

#Fail a build on a malicious or blocked dependency

POST /dependencies/check takes a list of package versions and returns a verdict for each: malicious, suspicious, vulnerable, clean or unknown. It also applies your organisation's supply chain policy: a package the policy blocks carries policy.action set to block, with the reason in policy.detail. Nothing is installed or run, and no repository is needed. Up to 500 packages per call. The details are on the package check API.

The step below reads package-lock.json, sends its packages in batches of 500, prints every malicious or blocked package and fails if there is one. It does not fail on vulnerable, suspicious or unknown; add those to the two jq expressions if you want to.

curl -fsS -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"packages":[{"ecosystem":"npm","name":"lodash","version":"4.17.20"}]}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/dependencies/check"

The answer, abridged:

{
  "results": [
    { "ecosystem": "npm", "name": "lodash", "version": "4.17.20", "verdict": "vulnerable", "advisories": [], "fixedVersion": "4.17.21", "reasons": [], "notes": [] }
  ],
  "malicious": 0,
  "suspicious": 0,
  "vulnerable": 1,
  "unknown": 0,
  "blocked": 0
}

#GitHub Actions: package check

name: Dependency check
on:
  pull_request:
    paths: ["package-lock.json"]

jobs:
  nullgap-packages:
    runs-on: ubuntu-latest
    env:
      NULLGAP_URL: ${{ vars.NULLGAP_URL }}
      NULLGAP_ORG: ${{ vars.NULLGAP_ORG }}
      NULLGAP_API_KEY: ${{ secrets.NULLGAP_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - name: Check packages with Nullgap
        run: |
          jq -c '[.packages | to_entries[]
                  | select(.key | contains("node_modules/"))
                  | select(.value.version != null and .value.link != true)
                  | {ecosystem: "npm", name: (.value.name // (.key | sub("^.*node_modules/"; ""))), version: .value.version}]
                 | unique | range(0; length; 500) as $i | {packages: .[$i:$i + 500]}' package-lock.json > batches.jsonl
          bad=0
          while read -r batch; do
            printf '%s' "$batch" > batch.json
            curl -fsS -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
              -H "Content-Type: application/json" \
              -d @batch.json -o verdicts.json \
              "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/dependencies/check"
            jq -r '.results[] | select(.verdict == "malicious" or .policy.action == "block")
                   | "\(.ecosystem):\(.name)@\(.version)  \(.verdict)  \(.policy.detail // "")"' verdicts.json
            bad=$((bad + $(jq '.malicious + .blocked' verdicts.json)))
          done < batches.jsonl
          if [ "$bad" -gt 0 ]; then
            echo "Nullgap: malicious or blocked packages found."
            exit 1
          fi

#GitLab CI: package check

nullgap-packages:
  stage: test
  image: alpine:3.20
  rules:
    - changes: ["package-lock.json"]
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      jq -c '[.packages | to_entries[]
              | select(.key | contains("node_modules/"))
              | select(.value.version != null and .value.link != true)
              | {ecosystem: "npm", name: (.value.name // (.key | sub("^.*node_modules/"; ""))), version: .value.version}]
             | unique | range(0; length; 500) as $i | {packages: .[$i:$i + 500]}' package-lock.json > batches.jsonl
      bad=0
      while read -r batch; do
        printf '%s' "$batch" > batch.json
        curl -fsS -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
          -H "Content-Type: application/json" \
          -d @batch.json -o verdicts.json \
          "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/dependencies/check"
        jq -r '.results[] | select(.verdict == "malicious" or .policy.action == "block")
               | "\(.ecosystem):\(.name)@\(.version)  \(.verdict)  \(.policy.detail // "")"' verdicts.json
        bad=$((bad + $(jq '.malicious + .blocked' verdicts.json)))
      done < batches.jsonl
      if [ "$bad" -gt 0 ]; then
        echo "Nullgap: malicious or blocked packages found."
        exit 1
      fi

For other ecosystems, build the same {"packages": [{"ecosystem", "name", "version"}]} body from your lockfile. Accepted ecosystem names include npm, pypi, cargo, go, maven, rubygems, packagist, nuget, hex and pub. Every entry needs an exact version.

#Export open findings as SARIF

GET /findings/export streams findings as csv, json or sarif. It takes the same filters as the findings list: state, severity, repoId, source, priority and q. An API key of any scope may call it, and each export is recorded in the audit log. See exports.

A code-scanning view expects results for the repository it belongs to, so the examples first look up the repository's id by its full name and then export only its open findings.

curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -o repositories.json \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories"
REPO_ID=$(jq -r --arg name "acme/shop" '.[] | select(.fullName == $name) | .id' repositories.json)

curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -o nullgap.sarif \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/export?format=sarif&state=open&repoId=$REPO_ID"

#GitHub Actions: SARIF export

This uploads the file to GitHub code scanning, which must be available for the repository.

name: Nullgap findings to code scanning
on:
  schedule:
    - cron: "0 6 * * *"
  workflow_dispatch:

jobs:
  nullgap-sarif:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    env:
      NULLGAP_URL: ${{ vars.NULLGAP_URL }}
      NULLGAP_ORG: ${{ vars.NULLGAP_ORG }}
      NULLGAP_API_KEY: ${{ secrets.NULLGAP_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - name: Export open findings
        run: |
          curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
            -o repositories.json \
            "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories"
          REPO_ID=$(jq -r --arg name "$GITHUB_REPOSITORY" '.[] | select(.fullName == $name) | .id' repositories.json)
          if [ -z "$REPO_ID" ]; then
            echo "This repository is not connected in Nullgap."
            exit 1
          fi
          curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
            -o nullgap.sarif \
            "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/export?format=sarif&state=open&repoId=$REPO_ID"
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: nullgap.sarif
          category: nullgap

#GitLab CI: SARIF export

GitLab keeps the file as a job artifact that you can download or pass to a later job.

nullgap-sarif:
  stage: test
  image: alpine:3.20
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
        -o repositories.json \
        "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories"
      REPO_ID=$(jq -r --arg name "$CI_PROJECT_PATH" '.[] | select(.fullName == $name) | .id' repositories.json)
      if [ -z "$REPO_ID" ]; then
        echo "This project is not connected in Nullgap."
        exit 1
      fi
      curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
        -o nullgap.sarif \
        "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/export?format=sarif&state=open&repoId=$REPO_ID"
  artifacts:
    when: always
    paths:
      - nullgap.sarif

#Gate a release on open critical and high findings

The findings list returns total for any filter, so a gate does not have to page: ask for one item and read the count. The step below fails when the repository has an open finding of critical or high severity.

Open means not fixed, not accepted as a risk and not marked a false positive; see triage. The gate counts every open finding whatever its assurance level, unverified ones included.

curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -o critical.json \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings?state=open&severity=critical&limit=1"
jq '.total' critical.json

#GitHub Actions: release gate

name: Release gate
on:
  push:
    tags: ["v*"]

jobs:
  nullgap-gate:
    runs-on: ubuntu-latest
    env:
      NULLGAP_URL: ${{ vars.NULLGAP_URL }}
      NULLGAP_ORG: ${{ vars.NULLGAP_ORG }}
      NULLGAP_API_KEY: ${{ secrets.NULLGAP_API_KEY }}
    steps:
      - name: No open critical or high findings
        run: |
          curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
            -o repositories.json \
            "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories"
          REPO_ID=$(jq -r --arg name "$GITHUB_REPOSITORY" '.[] | select(.fullName == $name) | .id' repositories.json)
          if [ -z "$REPO_ID" ]; then
            echo "This repository is not connected in Nullgap."
            exit 1
          fi
          blocking=0
          for severity in critical high; do
            curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
              -o findings.json \
              "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings?state=open&severity=$severity&repoId=$REPO_ID&limit=1"
            count=$(jq '.total' findings.json)
            echo "Open $severity findings: $count"
            blocking=$((blocking + count))
          done
          if [ "$blocking" -gt 0 ]; then
            echo "Nullgap: $blocking open critical or high findings. See $NULLGAP_URL/$NULLGAP_ORG/findings"
            exit 1
          fi

#GitLab CI: release gate

nullgap-gate:
  stage: deploy
  image: alpine:3.20
  rules:
    - if: $CI_COMMIT_TAG
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
        -o repositories.json \
        "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories"
      REPO_ID=$(jq -r --arg name "$CI_PROJECT_PATH" '.[] | select(.fullName == $name) | .id' repositories.json)
      if [ -z "$REPO_ID" ]; then
        echo "This project is not connected in Nullgap."
        exit 1
      fi
      blocking=0
      for severity in critical high; do
        curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
          -o findings.json \
          "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings?state=open&severity=$severity&repoId=$REPO_ID&limit=1"
        count=$(jq '.total' findings.json)
        echo "Open $severity findings: $count"
        blocking=$((blocking + count))
      done
      if [ "$blocking" -gt 0 ]; then
        echo "Nullgap: $blocking open critical or high findings. See $NULLGAP_URL/$NULLGAP_ORG/findings"
        exit 1
      fi

Put the job before the one that publishes, and make the publishing job depend on it.

#Start a pentest and wait for the result

POST /pentests starts a whitebox pentest of a connected repository. It needs a key with the admin scope.

If you want pentests at a regular rhythm and not tied to a release, a schedule is the better tool: it runs without a pipeline, can carry a ceiling for what one run may be charged, and never starts a run while the previous one is still going.

The request takes the repository's id and, optionally, a branch, tag or commit in ref (the default branch when omitted), folders in paths and notes for the tester in context. The full list of fields, including live testing, is in the pentests reference.

curl -fsS -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoId":"repo_123","ref":"main"}' \
  -o pentest.json \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests"
jq -r '.id, .status' pentest.json

Then poll GET /pentests/:id until status is no longer queued or running. It ends as completed, failed or cancelled. A completed pentest's answer includes its findings.

A pentest takes far longer than an ordinary build step. Give the job a generous timeout, or do not wait at all: start the pentest in one job and react to the pentest.completed webhook event instead.

#GitHub Actions: pentest

name: Pentest
on:
  workflow_dispatch:

jobs:
  nullgap-pentest:
    runs-on: ubuntu-latest
    timeout-minutes: 360
    env:
      NULLGAP_URL: ${{ vars.NULLGAP_URL }}
      NULLGAP_ORG: ${{ vars.NULLGAP_ORG }}
      NULLGAP_API_KEY: ${{ secrets.NULLGAP_ADMIN_API_KEY }}
    steps:
      - name: Start the pentest
        run: |
          curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
            -o repositories.json \
            "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories"
          REPO_ID=$(jq -r --arg name "$GITHUB_REPOSITORY" '.[] | select(.fullName == $name) | .id' repositories.json)
          if [ -z "$REPO_ID" ]; then
            echo "This repository is not connected in Nullgap."
            exit 1
          fi
          jq -n --arg repoId "$REPO_ID" --arg ref "$GITHUB_REF_NAME" '{repoId: $repoId, ref: $ref}' > request.json
          curl -fsS -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
            -H "Content-Type: application/json" \
            -d @request.json -o pentest.json \
            "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests"
          echo "PENTEST_ID=$(jq -r '.id' pentest.json)" >> "$GITHUB_ENV"
      - name: Wait for the result
        run: |
          echo "Follow it at $NULLGAP_URL/$NULLGAP_ORG/pentests/$PENTEST_ID"
          while true; do
            curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
              -o pentest.json \
              "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/$PENTEST_ID"
            status=$(jq -r '.status' pentest.json)
            if [ "$status" != "queued" ] && [ "$status" != "running" ]; then break; fi
            sleep 120
          done
          echo "Pentest $status"
          if [ "$status" != "completed" ]; then exit 1; fi
          blocking=$(jq '[.findings[] | select(.state == "open" and (.finding.severity == "critical" or .finding.severity == "high"))] | length' pentest.json)
          echo "Open critical or high findings from this pentest: $blocking"
          if [ "$blocking" -gt 0 ]; then exit 1; fi

#GitLab CI: pentest

nullgap-pentest:
  stage: test
  image: alpine:3.20
  timeout: 6h
  rules:
    - if: $CI_PIPELINE_SOURCE == "web"
      when: manual
  variables:
    NULLGAP_API_KEY: $NULLGAP_ADMIN_API_KEY
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
        -o repositories.json \
        "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories"
      REPO_ID=$(jq -r --arg name "$CI_PROJECT_PATH" '.[] | select(.fullName == $name) | .id' repositories.json)
      if [ -z "$REPO_ID" ]; then
        echo "This project is not connected in Nullgap."
        exit 1
      fi
      jq -n --arg repoId "$REPO_ID" --arg ref "$CI_COMMIT_REF_NAME" '{repoId: $repoId, ref: $ref}' > request.json
      curl -fsS -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
        -H "Content-Type: application/json" \
        -d @request.json -o pentest.json \
        "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests"
      PENTEST_ID=$(jq -r '.id' pentest.json)
      echo "Follow it at $NULLGAP_URL/$NULLGAP_ORG/pentests/$PENTEST_ID"
      while true; do
        curl -fsS -H "Authorization: Bearer $NULLGAP_API_KEY" \
          -o pentest.json \
          "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/$PENTEST_ID"
        status=$(jq -r '.status' pentest.json)
        if [ "$status" != "queued" ] && [ "$status" != "running" ]; then break; fi
        sleep 120
      done
      echo "Pentest $status"
      if [ "$status" != "completed" ]; then exit 1; fi
      blocking=$(jq '[.findings[] | select(.state == "open" and (.finding.severity == "critical" or .finding.severity == "high"))] | length' pentest.json)
      echo "Open critical or high findings from this pentest: $blocking"
      if [ "$blocking" -gt 0 ]; then exit 1; fi

Things that make the start fail, each with a message in the answer's error.message:

StatusCodeMeaning
403insufficient_scopeThe key does not have the admin scope.
403org_suspendedThe workspace is suspended.
402payment_required, usage_limit, over_capThe pentest cannot be paid for as things stand, the workspace has reached its usage limit, or the price is above the maxPriceUsd you sent.
404not_foundThe repository id is not one of your organisation's.
422checkout_failedThe code could not be fetched: the branch does not exist, or access was withdrawn.

With curl -f the step fails without showing the answer. To see the message while debugging, run the request once without -f.

A pentest started this way reads the code only. It does not test a running application unless you ask for live testing with the fields in the reference.

#With the nullgap command

The nullgap CLI does the same work as the curl steps above in one command each, with retries, waiting and exit codes built in. Its gate command fails a job when open findings at or above a severity exist, and writes SARIF and a Markdown summary.

What every recipe below has in common:

NameValueKind
NULLGAP_ORG_API_KEYAn API key. read is enough for the gate; starting a pentest needs admin.A secret
NULLGAP_URLThe address of your Nullgap console.A variable
NULLGAP_CLI_IMAGEThe container image of the CLI that you were given or built. Its entry point is the nullgap command.A variable

The CLI reads the key from NULLGAP_ORG_API_KEY, not from NULLGAP_API_KEY: in the CLI that second name is the key of the model endpoint of its local commands. It finds the organisation from the key, so NULLGAP_ORG is not needed. Never pass the key as an argument.

The recipes gate a pull request on its Nullgap review. --commit makes the gate wait for the review of the commit being built instead of accepting an older one, and it waits up to 30 minutes by default (--timeout). The exit codes are listed on the CLI page: 2 means blocking findings, 6 that the review did not finish in time.

#GitHub Actions: gate with the CLI

A copy of this workflow is in the repository as examples/github-actions/nullgap-gate.yml.

name: Nullgap gate
on:
  pull_request:

permissions:
  contents: read
  security-events: write

jobs:
  nullgap-gate:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    if: github.event.pull_request.head.repo.full_name == github.repository
    env:
      NULLGAP_URL: ${{ vars.NULLGAP_URL }}
      NULLGAP_ORG_API_KEY: ${{ secrets.NULLGAP_ORG_API_KEY }}
      NULLGAP_CLI_IMAGE: ${{ vars.NULLGAP_CLI_IMAGE }}
      PR_NUMBER: ${{ github.event.pull_request.number }}
      HEAD_SHA: ${{ github.event.pull_request.head.sha }}
    steps:
      - uses: actions/checkout@v4
      - name: Gate on the Nullgap review of this pull request
        run: |
          mkdir -p nullgap-out
          docker run --rm --user "$(id -u):$(id -g)" \
            -e NULLGAP_URL -e NULLGAP_ORG_API_KEY \
            -v "$PWD/nullgap-out:/work" "$NULLGAP_CLI_IMAGE" \
            gate --repo "$GITHUB_REPOSITORY" --pr "$PR_NUMBER" --commit "$HEAD_SHA" \
            --fail-on high --sarif nullgap.sarif --md summary.md
      - name: Add the summary to the job page
        if: always()
        run: if [ -f nullgap-out/summary.md ]; then cat nullgap-out/summary.md >> "$GITHUB_STEP_SUMMARY"; fi
      - uses: github/codeql-action/upload-sarif@v3
        if: always() && hashFiles('nullgap-out/nullgap.sarif') != ''
        with:
          sarif_file: nullgap-out/nullgap.sarif
          category: nullgap

The upload step needs GitHub code scanning to be available for the repository; leave it out otherwise. On a pull_request event GITHUB_SHA is a merge commit that Nullgap never saw, which is why the head commit is taken from the event.

#GitLab CI: gate with the CLI

Store NULLGAP_ORG_API_KEY as a masked, protected CI/CD variable.

nullgap-gate:
  stage: test
  image:
    name: $NULLGAP_CLI_IMAGE
    entrypoint: [""]
  timeout: 45m
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - nullgap gate --repo "$CI_PROJECT_PATH" --pr "$CI_MERGE_REQUEST_IID" --commit "$CI_COMMIT_SHA"
      --fail-on high --sarif nullgap.sarif --md nullgap-summary.md
  artifacts:
    when: always
    paths:
      - nullgap.sarif
      - nullgap-summary.md

In a merged-results pipeline CI_COMMIT_SHA is a merge commit that Nullgap never saw: use $CI_MERGE_REQUEST_SOURCE_BRANCH_SHA there.

#Bitbucket Pipelines: gate with the CLI

Store NULLGAP_ORG_API_KEY as a secured repository variable. Bitbucket does not expand variables in image, so write the image's name there.

image: registry.acme.example/nullgap-cli:latest

pipelines:
  pull-requests:
    '**':
      - step:
          name: Nullgap gate
          max-time: 45
          script:
            - nullgap gate --repo "$BITBUCKET_REPO_FULL_NAME" --pr "$BITBUCKET_PR_ID" --commit "$BITBUCKET_COMMIT"
              --fail-on high --sarif nullgap.sarif --md nullgap-summary.md
          artifacts:
            - nullgap.sarif
            - nullgap-summary.md

#Azure Pipelines: gate with the CLI

Store NULLGAP_ORG_API_KEY as a secret variable. Azure does not hand secret variables to scripts on its own: the env block below is what passes it, and only to this step.

trigger: none
pr:
  branches:
    include: ['*']

pool:
  vmImage: ubuntu-latest

steps:
  - script: |
      mkdir -p "$(Build.ArtifactStagingDirectory)/nullgap"
      docker run --rm --user "$(id -u):$(id -g)" \
        -e NULLGAP_URL -e NULLGAP_ORG_API_KEY \
        -v "$(Build.ArtifactStagingDirectory)/nullgap:/work" "$NULLGAP_CLI_IMAGE" \
        gate --repo "$REPOSITORY" --pr "$PR_NUMBER" --commit "$HEAD_SHA" \
        --fail-on high --sarif nullgap.sarif --md summary.md
    displayName: Nullgap gate
    timeoutInMinutes: 45
    env:
      NULLGAP_URL: $(NULLGAP_URL)
      NULLGAP_ORG_API_KEY: $(NULLGAP_ORG_API_KEY)
      NULLGAP_CLI_IMAGE: $(NULLGAP_CLI_IMAGE)
      REPOSITORY: $(Build.Repository.Name)
      PR_NUMBER: $(System.PullRequest.PullRequestId)
      HEAD_SHA: $(System.PullRequest.SourceCommitId)
  - publish: $(Build.ArtifactStagingDirectory)/nullgap
    artifact: nullgap
    condition: always()

For a repository hosted on GitHub, the pull request's number is in System.PullRequest.PullRequestNumber.

--repo takes the repository's name as nullgap repos prints it. If your pipeline's name for the repository differs from that, write the name out.

#Other things a pipeline can do with the CLI

Gate a release on every open finding of the repository, proven ones only:

nullgap gate --repo acme/shop --fail-on high --proven-only

Start a pentest of a release and wait for it, accepting a price up to a limit, then gate on its result. The idempotency key makes a re-run of the job return the same pentest, not start a second one:

nullgap pentest start acme/shop --ref "$TAG" --max-price 500 --idempotency-key "release-$TAG" --wait --timeout 360
nullgap gate --repo acme/shop --ref "$TAG" --fail-on high --sarif nullgap.sarif

A paid run never starts in a pipeline without --yes or --max-price.

Nullgap documentation