Add Keryn to CI
Run Keryn on every pull request in your pipeline, fail the job on what you decided should fail it, and publish the outputs your platform understands: SARIF, the AI-BOM, test reports and a summary.
Stage the reviewed private CLI archive on your runner and set KERYN_CLI_TARBALL to its local path.
Every CI integration is the same CLI call. The pipeline installs a pinned @keryn/cli, runs keryn scan, publishes the outputs its platform understands, and uses Keryn’s exit code as the job result. Source analysis reads the checkout. The CI credential uses the Keryn entitlement service, and online advisory checks require an explicit option.
Before you start
Section titled “Before you start”- A repository with a base branch to compare against, and a runner with Node.js 22 or later (or the single binary or the container image).
- A decision on what fails a job: errors (
--fail-on error, the default), any new AI component (--fail-on-added), or your policy. - A full clone in the job (
fetch-depth: 0): diffing against a base needs the base commit.
1. The call
Section titled “1. The call”npm install --offline --ignore-scripts --global --prefix "$HOME/.local" "$KERYN_CLI_TARBALL"export PATH="$HOME/.local/bin:$PATH"keryn scan . \ --policy .keryn/policy.yml \ --base "$BASE_SHA" \ --sarif keryn-out/keryn.sarif --aibom keryn-out/keryn.cdx.json \ --json keryn-out/result.json --junit keryn-out/keryn-junit.xml \ --markdown keryn-out/summary.mdPin an exact version. Diffing against a base needs the base commit in the clone, so fetch full history (fetch-depth: 0, GIT_DEPTH: 0).
| Exit | Meaning | Suggested job result |
|---|---|---|
| 0 | pass | success |
| 10 | pass with warnings (only with --exit-warn) |
success with warning |
| 1 | policy violations or findings at or above --fail-on |
failure |
| 2, 3, 4 | usage error, incomplete coverage, internal error | failure, with the reason in the log |
Permission to scan in a job
Section titled “Permission to scan in a job”A release build of the CLI scans only when it has permission: a sign-in to your organization, or an offline licence. A job cannot open a browser, so it uses a credential from the environment (see sign in, entitlements and offline licences for the rest).
- An organization administrator issues the credential once in Account, Developers, CI credential. It is a service account that lasts at most 90 days. It belongs to the organization, not to a person, and takes one device slot however many jobs use it. It is revoked in the same place and stops working at its next request.
- Store it as a secret named
KERYN_TOKENin your CI system and expose it to the steps that install and scan. Nothing else: nokeryn login, no file.
The CLI uses an installed offline licence first, then KERYN_TOKEN, then a stored keryn login. With KERYN_TOKEN set, a login left on the runner is not read, so a job never acts as whoever signed in before. The token goes only to the Keryn service, is never written to disk or printed, and every job gets a fresh device key and entitlement. A value that is not shaped like a token is ignored, so a job with a mistyped secret is simply not signed in:
KERYN_TOKEN=short keryn whoamiNot signed in. Run `keryn login` (or `keryn licence install <file>` for an offline licence).Changes from forks. A pull or merge request from a fork does not receive secrets on any of these platforms, so it has no KERYN_TOKEN. The job must not pretend it scanned: it fails, saying the change was not scanned and a maintainer must run the scan from a branch of the repository. Do not work around it with pull_request_target, which runs the fork’s code with your secret.
When the run is incomplete
Section titled “When the run is incomplete”Exit 3 means Keryn could not look at everything it needed to, and it is never reported as a pass. A common cause in CI is lockfiles that were not checked against advisories because the job is offline. --require-advisories turns that into a failure:
keryn scan . --require-advisoriesThe verdict line says Incomplete: dependency advisories not checked (offline) and the summary shows Analysis: incomplete. Either give the job an advisory snapshot or --online (see the SCA guide), or accept the gap on purpose by leaving the flag off; the verdict still says the advisories were not checked. Rules that were unsupported, partial or timed out also exit 3 unless you pass --allow-incomplete; do that only when you have decided an incomplete rule run is acceptable for that job.
2. Rehearse the job on your machine
Section titled “2. Rehearse the job on your machine”Run the same call before you write the pipeline. This one is the fixture of this page’s tests: a change that adds a second provider, compared with origin/main.
mkdir -p keryn-outkeryn scan . --base origin/main --fail-on-added \ --sarif keryn-out/keryn.sarif --aibom keryn-out/keryn.cdx.json \ --json keryn-out/result.json --junit keryn-out/keryn-junit.xml \ --markdown keryn-out/summary.md --quiet || echo "exit code $?"ls keryn-outexit code 1keryn-junit.xmlkeryn.cdx.jsonkeryn.sarifresult.jsonsummary.md--quiet keeps the log short; the files carry everything. Exit 1 is the job result: this change has findings at error and adds components. The summary is what you post as a comment or a step summary:
grep -m1 '^\*\*Keryn' keryn-out/summary.md | sed -E 's/(/(/g; s/)/)/g'**Keryn — Policy blocked (Hold); dependency advisories not checked (offline)**The examples use keryn-out/ as an artifact staging directory. Start each scan from a clean checkout, or write reports and evidence bundles outside the scanned tree if you reuse the checkout. This keeps earlier outputs out of later scans.
3. Your platform
Section titled “3. Your platform”Install the reviewed archive as in step 1 before these scan steps, or provision that exact CLI version on the runner. Pick the section for your CI; each is the same call with the platform’s way of publishing the outputs.
The GitLab, Azure Pipelines, Bitbucket and Jenkins examples below match the templates in Keryn’s source (a GitLab include: template and CI/CD component, an Azure steps template, a Jenkins shared-library step, a Bitbucket snippet). The templates are not published anywhere yet: you copy them. Their script runs locally in Keryn’s tests, but a green run on each platform is still pending, so treat them as a starting point you verify in your own pipeline.
GitHub Actions
Section titled “GitHub Actions”Stage the approved archive on a Linux runner labeled keryn-ci and dedicated to trusted repository branches. Set the repository variable KERYN_CLI_TARBALL to its local path and configure the KERYN_TOKEN secret. The fork job runs separately, with no checkout or Keryn credential.
name: kerynon: [pull_request]permissions: contents: read security-events: write # SARIF upload to code scanningjobs: fork: if: github.event.pull_request.head.repo.full_name != github.repository runs-on: ubuntu-latest permissions: {} steps: - run: | echo "::error::Keryn has no CI credential for this fork. A maintainer must review the change and run it from a branch of the repository." exit 1 scan: if: github.event.pull_request.head.repo.full_name == github.repository runs-on: [self-hosted, linux, keryn-ci] steps: - uses: actions/checkout@v4 with: { fetch-depth: 0 } - uses: actions/setup-node@v4 with: { node-version: 24 } - name: Install the staged CLI env: KERYN_CLI_TARBALL: ${{ vars.KERYN_CLI_TARBALL }} run: | test -f "$KERYN_CLI_TARBALL" install_dir="$RUNNER_TEMP/keryn-cli" npm install --offline --ignore-scripts --global --prefix "$install_dir" "$KERYN_CLI_TARBALL" echo "$install_dir/bin" >> "$GITHUB_PATH" - name: Scan env: KERYN_TOKEN: ${{ secrets.KERYN_TOKEN }} run: | mkdir -p keryn-out keryn scan . --policy .keryn/policy.yml \ --base "${{ github.event.pull_request.base.sha }}" --annotations github \ --sarif keryn-out/keryn.sarif --aibom keryn-out/keryn.cdx.json --markdown keryn-out/summary.md - if: always() && hashFiles('keryn-out/summary.md') != '' run: cat keryn-out/summary.md >> "$GITHUB_STEP_SUMMARY" - if: always() && hashFiles('keryn-out/keryn.sarif') != '' uses: github/codeql-action/upload-sarif@v3 with: { sarif_file: keryn-out/keryn.sarif, category: keryn }Pin third-party actions by commit SHA in your own workflows. The copy-in workflow handles forks before checkout. For trusted scans, the workflow’s optional upload-sarif step sends the generated SARIF report to GitHub. Enable code scanning in the repository before using that step.
The Keryn composite action is tested locally and distributed through reviewed private channels when qualified. It can take a private CLI tarball and its SHA-256, install it offline, and attach reports and optional status updates. Scans that use a CI credential still contact the entitlement service.
For a per-pull-request Check that is bound to the exact base and head commits and computed in your own runner, see the GitHub App, which is source only and in the next release.
GitLab CI/CD
Section titled “GitLab CI/CD”keryn-scan: image: node:24-bookworm-slim variables: { GIT_DEPTH: "0" } script: - mkdir -p keryn-out - keryn scan . --policy .keryn/policy.yml ${CI_MERGE_REQUEST_DIFF_BASE_SHA:+--base $CI_MERGE_REQUEST_DIFF_BASE_SHA} --annotations gitlab --gitlab-sast keryn-out/gl-sast-report.json --codequality keryn-out/gl-code-quality-report.json --junit keryn-out/keryn-junit.xml --aibom keryn-out/keryn.cdx.json artifacts: when: always paths: [keryn-out/] reports: sast: keryn-out/gl-sast-report.json codequality: keryn-out/gl-code-quality-report.json junit: keryn-out/keryn-junit.xml cyclonedx: keryn-out/keryn.cdx.jsonThe SAST report feeds the Security tab and the merge request widget; Code Quality and JUnit feed their widgets. The CycloneDX dependency list depends on your GitLab tier.
Azure Pipelines
Section titled “Azure Pipelines”steps: - checkout: self fetchDepth: 0 - task: NodeTool@0 inputs: { versionSpec: "24.x" } - script: | mkdir -p keryn-out keryn scan . --policy .keryn/policy.yml --annotations azure \ --junit keryn-out/keryn-junit.xml --sarif keryn-out/keryn.sarif --aibom keryn-out/keryn.cdx.json displayName: keryn scan - task: PublishTestResults@2 condition: always() inputs: { testResultsFormat: JUnit, testResultsFiles: keryn-out/keryn-junit.xml } - publish: keryn-out artifact: keryn condition: always()--annotations azure writes the findings to the run’s Issues pane. The SARIF file is what the SARIF SAST Scans Tab extension reads.
Bitbucket Pipelines
Section titled “Bitbucket Pipelines”pipelines: pull-requests: '**': - step: name: keryn scan image: node:24-bookworm-slim script: - mkdir -p keryn-out - keryn scan . --policy .keryn/policy.yml --base "$BITBUCKET_PR_DESTINATION_COMMIT" --sarif keryn-out/keryn.sarif --aibom keryn-out/keryn.cdx.json --junit keryn-out/test-results/keryn.xml artifacts: [keryn-out/**]Bitbucket picks up JUnit files under test-results/ on its own.
Jenkins
Section titled “Jenkins”stage('keryn') { steps { sh ''' mkdir -p keryn-out keryn scan . --policy .keryn/policy.yml \ --junit keryn-out/keryn-junit.xml --sarif keryn-out/keryn.sarif --aibom keryn-out/keryn.cdx.json ''' } post { always { junit 'keryn-out/keryn-junit.xml' archiveArtifacts artifacts: 'keryn-out/**' // Warnings Next Generation: recordIssues tool: sarif(pattern: 'keryn-out/keryn.sarif') } }}Coding agents (Keryn Skills)
Section titled “Coding agents (Keryn Skills)”With a coding agent, the eight project skills in Keryn Skills connect it to the CLI and the Keryn MCP server.
Air-gapped runners
Section titled “Air-gapped runners”Use the single binary or the container image, or install the npm tarball from your artifact repository with npm install --offline <keryn-cli-<version>.tgz>. Install an offline licence before disconnecting the runner. The scan can then run offline, and the rules ship inside the package. The whole procedure, with a way to prove the network is not used, is in air-gapped use.
Speed up reruns
Section titled “Speed up reruns”Scans of an unchanged tree are answered from a local report. A job that caches KERYN_CACHE_DIR between runs gets that for free on a re-run of the same commit. A scan with --base is never answered from it. See the rescan cache.
What you just proved
Section titled “What you just proved”The pipeline’s decision is made on your runner from your checkout, with a pinned tool, and the exit code means one documented thing. A job using a CI credential needs to reach the Keryn entitlement service before it can scan. For runners that must scan without that connection, install a valid offline licence before disconnecting. Advisory lookups and report uploads have their own network requirements when enabled. Keep the base commit available locally so the CLI can compare it with the head commit.
- Let the exit code follow your team’s answers (Go, Go with accepted risk, Hold): release decisions.
- Fail only on what a change adds: baselines and deltas.
- Accept an exception with an owner and an expiry: suppressions.
- Keep the evidence of every release: evidence for auditors.