# Add Keryn to CI

> Run keryn scan in any pipeline, gate on policy and on what a change adds, and publish SARIF, AI-BOM and test reports.

Source: https://keryn.dev/docs/guides/ci/

## Goal

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.

> **Note: CLI prerequisite**
> This walkthrough is tested with a private CLI package built from the current source. Release 0.5.2 lacks `keryn whoami` and `keryn scan --require-advisories`, and its report summary differs from the recorded example. Before using the walkthrough, check that your staged CLI supports both with `keryn whoami --help` and `keryn scan --help`. See the [keryn.app download page](https://keryn.app/download) for member download availability.

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

- 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](https://keryn.dev/docs/guides/policies/).
- A full clone in the job (`fetch-depth: 0`): diffing against a base needs the base commit.

## 1. The call

```sh
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 |

## 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](https://keryn.dev/docs/guides/entitlements/) 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:

```sh
KERYN_TOKEN=short keryn whoami
```

```text
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.

## 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:

```sh
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](https://keryn.dev/docs/guides/sca/)), 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

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

```sh
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
```

```text
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:

```sh
grep -m1 '^\*\*Keryn' keryn-out/summary.md | sed -E 's/&#40;/(/g; s/&#41;/)/g'
```

```text
**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

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

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.

```yaml
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](https://keryn.dev/docs/guides/github-app/), which is source only and in the next release.

### GitLab CI/CD

```yaml
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.

### Azure Pipelines

```yaml
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

```yaml
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

```groovy
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)

With a coding agent, the eight project skills in [Keryn Skills](https://keryn.dev/docs/guides/keryn-skills/) connect it to the CLI and the Keryn MCP server.

## 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](https://keryn.dev/docs/guides/air-gapped/).

## 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](https://keryn.dev/docs/guides/rescan-cache/).

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

## Next

- Let the exit code follow your team's answers (Go, Go with accepted risk, Hold): [release decisions](https://keryn.dev/docs/guides/release-decisions/).
- Fail only on what a change adds: [baselines and deltas](https://keryn.dev/docs/guides/baselines/).
- Accept an exception with an owner and an expiry: [suppressions](https://keryn.dev/docs/guides/suppressions/).
- Keep the evidence of every release: [evidence for auditors](https://keryn.dev/docs/guides/auditors/).
