Skip to content

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

    GitHub Action

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    AI-BOM (CycloneDX 1.6), rule findings and policy gate for a repository, with SARIF upload and a step summary. Local, deterministic, no telemetry. A composite action (ts/clients/github-action/action.yml); the CI guide shows the other pipeline platforms.

    on: pull_request
    permissions:
    contents: read
    security-events: write # upload-sarif
    pull-requests: write # comment
    jobs:
    keryn:
    runs-on: ubuntu-24.04
    steps:
    - uses: actions/checkout@<full-commit-sha>
    with:
    persist-credentials: false
    fetch-depth: 0
    ref: ${{ github.event.pull_request.head.sha || github.sha }}
    - uses: <path or repository of the Keryn Action>@<full-commit-sha>
    with:
    tarball: vendor/keryn-cli-0.5.2.tgz
    tarball-sha256: <sha256 of that file>
    policy: .keryn/policy.yml
    comment: true

    Set both tarball and tarball-sha256. The action rejects a nonempty version input.

    Input Default Description
    path . Directory to scan, relative to the workspace.
    rules empty Rule files or bundled packs, comma-separated (keryn scan –rules). Empty keeps the CLI default (bundled:all, the whole library, with Deep); bundled:aibom for inventory only.
    policy empty Policy-as-code YAML (keryn scan –policy). Empty means no policy.
    fail-on error Gate threshold (error | warning | info | none).
    fail-on-unsupported false Kept for compatibility. The CLI already exits 3 when rules were unsupported, partial or timed out, whatever this says; set allow-incomplete to accept incomplete coverage instead.
    allow-incomplete false Do not exit 3 when coverage is incomplete (keryn scan –allow-incomplete). The job then passes or fails on the findings alone; the report still says what was not covered.
    fail-on-added false With base-ref, exit 1 when components were added.
    exit-warn false Exit 10 for pass-with-warnings (mapped to a workflow warning, not a failure).
    base-ref ${{ github.event.pull_request.base.sha }} Git ref to diff against (keryn scan –base). Defaults to the pull request base; empty disables the diff. Needs fetch-depth 0.
    new-only false Gate only new findings against the paired Git base. Requires a CLI release containing –new-only; incomplete comparisons fail closed.
    summary-by empty Group findings by a framework taxonomy in the summary (owasp_llm | owasp_agentic | cwe | nist_ai_rmf | atlas); reference only.
    version empty Not supported. The keryn CLI is not published to npm. Download keryn-cli-<version>.tgz from https://keryn.app/download after signing in and pass it as tarball with tarball-sha256. Giving version stops the action with that instruction.
    tarball empty Path to a keryn-cli-<version>.tgz (npm pack of the CLI), absolute or relative to the workspace. Installed offline.
    tarball-sha256 empty Expected SHA-256 of the tarball; the action stops before installing when it differs.
    token empty A Keryn CI credential, from a secret. An organization administrator issues it as a service account in Account > Developers. The CLI reads it as KERYN_TOKEN, signs the run in without a browser, and never stores or prints it. Leave empty for a build of the CLI that needs no sign-in.
    server empty The Keryn service the credential belongs to. Empty means api.keryn.app.
    require-token false Set to true when the CLI is a release build that scans only when signed in. Without a token the job then stops before installing anything, with the reason. A pull request from a fork never receives the secret, so its check fails and says a maintainer must run the scan; it is never skipped as passed.
    node-version 24 Node.js version for the CLI.
    upload-sarif true Upload the SARIF to GitHub code scanning (needs security-events write).
    sarif-category keryn Code scanning category of the upload.
    upload-bom true Upload the AI-BOM, SARIF and JSON as a workflow artifact.
    step-summary true Append the markdown summary to the job summary.
    annotations true Emit GitHub annotations for findings (keryn scan –annotations github).
    attribution false Include PR attribution and evaluate the PR base’s .keryn.yml attribution gate and .keryn/policy.yml AI usage rules. Requires a CLI with attribution pr.
    output-dir empty Where the outputs are written. Existing Keryn report files in this directory are refused.
    comment false On pull requests, post the markdown summary as a PR comment and update it in place on later pushes (needs pull-requests write).
    github-token empty Token for the PR comment; defaults to the workflow token. Fork pull requests get a read-only token, so the comment is skipped with a warning.
    commit-status false Set a commit status keryn/&lt;sarif-category> on the scanned commit from the CLI verdict (success on 0 and 10, failure on 1, error otherwise; needs statuses write). Idempotent per context.

    A path output is set only when the file exists. Outputs are written before the step that fails the job.

    Output Description
    exit-code The CLI’s exit code (0 pass, 1 violations, 2 usage, 3 coverage, 4 internal, 10 warnings).
    sarif Path of the SARIF 2.1.0 file.
    aibom Path of the CycloneDX 1.6 AI-BOM.
    json Path of the Keryn result JSON.
    markdown Path of the markdown summary.
    Permission Needed for
    contents: read always
    security-events: write upload-sarif
    pull-requests: write comment
    statuses: write commit-status

    The action needs no secret: comment and commit-status use the workflow token (or github-token). The scan makes no network call; a tarball install is npm install --offline --ignore-scripts. The third-party actions it calls are pinned by full commit SHA.

    • Only pull_request runs. pull_request_target is refused before anything is installed.
    • The scan refuses to run unless the checked-out HEAD is the pull request’s head commit.
    • For a pull request from a fork, the comment, the commit status and the SARIF upload are skipped (no privileged token). The scan, annotations, the job summary, the artifact and the job’s exit code (the required check) still run.
    • Pin the action by full commit SHA, check out with persist-credentials: false, and protect the workflow and the base policy with rulesets or CODEOWNERS.

    The CLI’s code is the exit-code output; the last step turns it into the job’s result: 0 passes, 10 (pass with warnings, with exit-warn) passes with a workflow warning, anything else fails the job with that code (1 findings or policy, 2 usage or configuration, 3 coverage incomplete, 4 internal error). The final error or warning names the gate’s reasons; they are also in the job summary and the result JSON.

    Incomplete coverage (an unsupported, partial or timed-out rule) exits 3 by default. Set allow-incomplete: true to pass or fail on the findings alone; the report still says what was not covered. fail-on-unsupported is kept for compatibility and changes nothing.

    With commit-status, the status keryn/<sarif-category> is success for 0 and 10, failure for 1, error otherwise.

    • Annotations (annotations): one per assessment case, not per rule hit: error when the case blocks, warning otherwise, plus a keryn.coverage warning when coverage is incomplete.
    • Sticky comment (comment): one comment per pull request and sarif-category, marked <!-- keryn-comment:<category> --> and updated on every push. The comment is found by the login of the token that writes it, so a custom github-token updates its own comment too; nobody else’s comment is touched. Bodies over 60,000 bytes are cut with a pointer to the job summary. A failure to post is a warning and does not change the exit code.
    • SARIF (upload-sarif): uploaded to code scanning under sarif-category, with baselineState (new, unchanged) when base-ref is set, and the repository and revision recorded.
    • Artifact (upload-bom): the AI-BOM, SARIF and result JSON, kept 30 days.

    new-only: true scans base-ref with the same pipeline and gates only findings the base does not have. A comparison that is not like for like (different engine or rule versions, a different rule set or exclusions, incomplete coverage on either side, a finding without a fingerprint) exits 3: no passing delta gate is issued. The verdict reads New-findings checks passed (release approval not assessed): it is not a release decision, and .keryn/decisions.yml does not apply in this mode. fail-on-added with new-only is refused (exit 2).

    • On GitHub Enterprise Server without code scanning, set upload-sarif: false; GHES has not been tested.
    • The reusable workflow (.github/workflows/keryn-scan-reusable.yml, new-only defaulting to true) forwards only version, which the action rejects. Use the composite action with a staged tarball as shown above.