# GitHub Action

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> Keryn Action: every input and output (generated from its action.yml), permissions, the fork-safe model, exit codes, the sticky comment and SARIF upload. Not published yet.

Source: https://keryn.dev/docs/reference/github-action/

> **Caution: Not published yet**
> The action is available in the source repository. To run it, stage a private CLI package, set `tarball` and `tarball-sha256`, and leave `version` empty. Check the [keryn.app download page](https://keryn.app/download) for member download availability. `--new-only` (input `new-only`) needs a release after 0.5.2.

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](https://keryn.dev/docs/guides/ci/) shows the other pipeline platforms.

## Example

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

## Inputs

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-&lt;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-&lt;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. |

## Outputs

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

## Permissions

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

## Fork-safe model

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

## Exit codes

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, comment, SARIF

- **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 findings only

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

## Known gaps

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