Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Add Keryn to CI

    View as Markdown

    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.

    • 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.
    Terminal window
    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.md

    Pin 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

    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).

    1. 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.
    2. Store it as a secret named KERYN_TOKEN in your CI system and expose it to the steps that install and scan. Nothing else: no keryn 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:

    Terminal window
    KERYN_TOKEN=short keryn whoami
    Not 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.

    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:

    Terminal window
    keryn scan . --require-advisories

    The 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.

    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.

    Terminal window
    mkdir -p keryn-out
    keryn 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-out
    exit code 1
    keryn-junit.xml
    keryn.cdx.json
    keryn.sarif
    result.json
    summary.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:

    Terminal window
    grep -m1 '^\*\*Keryn' keryn-out/summary.md | sed -E 's/&#40;/(/g; s/&#41;/)/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.

    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.

    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: keryn
    on: [pull_request]
    permissions:
    contents: read
    security-events: write # SARIF upload to code scanning
    jobs:
    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.

    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.json

    The 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.

    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.

    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.

    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')
    }
    }
    }

    With a coding agent, the eight project skills in Keryn Skills connect it to the CLI and the Keryn MCP server.

    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.

    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.

    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.