# Release decisions

> Turn a scan into Go, Go with accepted risk or Hold, record your answers to findings in .keryn/decisions.yml, sign the decision, export OpenVEX and open issues for what is held.

Source: https://keryn.dev/docs/guides/release-decisions/

## Goal

Answer one question for a change: **can it go out, and on what terms?** Keryn proposes one of three labels from the scan and from your repository's own answers to its findings, and a person signs it.

| Label | When | Exit code |
|---|---|---|
| **Hold** | a finding at or above `--fail-on` has no live answer, is under investigation, is affected without acceptance, or its answer expired; or the policy is broken | 1 |
| **Go with accepted risk** | everything gating is answered, and at least one answer is an accepted risk (who, until when, the ticket) | 0 (10 with `--exit-warn`) |
| **Go** | nothing gating is open and no risk is accepted | 0 |

The codes are the ones `keryn scan` already uses, so a CI job does not change. Every decision also prints what the scan could not read: a Go with incomplete coverage says so on the same line. Keryn never says a release is fine to ship; it says what is open and what was accepted, by whom.

## Before you start

- The Keryn CLI ([install](https://keryn.dev/docs/start/install/)) and a repository with findings you have **looked at**. An answer records a decision about a finding; to work out whether a finding is real, [read its attack chain](https://keryn.dev/docs/guides/attack-chain/) first.
- Answers live in the repository, next to the code, and change through pull requests like the code does.

## 1. Ask for the decision

```sh
keryn decide .
```

With no answers yet, every gating finding is a **Hold**. Each Hold names the finding, the edge it sits on and its proof level. When the trust model places the file on a chain, the edge is that chain's step, for example `flow.user_input: User prompt -> agent.py agent (OpenAI SDK)`. Otherwise it is the finding's `file:line -> rule`.

## 2. Answer the findings

Create `.keryn/decisions.yml`. Each entry answers one finding by its fingerprint (`keryn scan --json` lists them), or every finding of a rule in a path with `match`:

```yaml
apiVersion: keryn.dev/decisions/v1
decisions:
  - match: {rule: seceng/shell_exec, path: agent.py}
    status: affected
    accepted: true
    reason: Internal tool behind the VPN; the command allow-list ships with the agent rewrite.
    ticket: https://github.com/example/app/issues/142
    expires: 2027-01-31
    decided_by: dana@example.com
    decided_at: 2026-11-08
  - match: {rule: python.code-execution.llm-output-to-subprocess, path: agent.py}
    status: under_investigation
    reason: Checking whether the prompt can carry user text.
    decided_by: dana@example.com
    decided_at: 2026-11-08
```

| Field | Meaning |
|---|---|
| `status` | `not_affected`, `affected`, `fixed` or `under_investigation` (the OpenVEX statuses) |
| `justification` | required for `not_affected`: one of the OpenVEX justifications, such as `vulnerable_code_not_in_execute_path` |
| `accepted`, `expires` | an accepted risk is `affected` with `accepted: true` and an expiry date; after that date it is a Hold again |
| `reason`, `decided_by`, `decided_at` | required on every entry: why, who, when |
| `ticket`, `owner` | optional; `keryn decide export` fills `ticket` |

```sh
keryn decide .
```

The accepted risks now print with who accepted them and until when. Whatever is still unanswered, or under investigation, stays a Hold. Answer the rest and the label becomes **Go with accepted risk**.

The files under `.keryn/` (`decisions.yml`, `scope.yml`, `releases.jsonl`) are records, not code: a scan never reads them as source, and the coverage line counts them separately.

## 3. Say what is in scope and what is not covered

`.keryn/scope.yml` states the scope and the coverage you declare. It prints on every decision and in the hand-off reports, so nobody reads a Go as "everything was checked".

```yaml
apiVersion: keryn.dev/scope/v1
in_scope:
  - {path: "services/**", note: "customer-facing agents"}
exclusions:
  - {path: "vendor/**", reason: "Third-party code, scanned upstream.", decided_by: dana@example.com, decided_at: 2026-11-08}
coverage:
  - {area: python services, status: covered}
  - {area: runtime behaviour, status: not_covered, note: "Keryn reads code and config; nothing watches production."}
```

Once either file exists, `keryn scan` prints the decision as well and carries it in `--json` as `decision` (`label`, `holds`, `acceptedRisks`, `coverage`, `signed`). A repository without them behaves exactly as before.

## 4. Sign it

A decision is *proposed* by Keryn and *signed* by a person. The example answers above still leave a Hold under investigation, so this command refuses to sign until it is resolved:

```sh
keryn decide sign .
```

`sign` records `git config user.email` (shown before it writes; nobody can sign as another name) in `.keryn/releases.jsonl`, each record chained to the previous one by hash. It refuses a Hold, and it refuses to run when `CI` is set: a pipeline proposes, a person signs. To make a signature mandatory, set `release: {require_signature: true}` in the [policy file](https://keryn.dev/docs/reference/policy/); an unsigned Go then exits 1.

## 5. Move existing suppressions over

`suppress:` entries in `.keryn.yml` and policy waivers keep working. For example, this legacy entry is tied to the reviewed finding in `agent.py`:

```yaml
apiVersion: keryn.dev/config/v1
suppress:
  - rule: seceng.llm05.python-subprocess-shell-true
    path: agent.py
    reason: Fixed command allow-list reviewed in SEC-123.
    owner: platform-security
    ticket: SEC-123
    expires: 2028-01-31
```

To turn legacy entries into answers:

```sh
keryn decide migrate .
keryn decide migrate . --write
keryn decide migrate . --write --remove-legacy
```

The first command prints the decisions it would add, one per finding the old entry covers today. `--write` adds them to `.keryn/decisions.yml` and leaves the old entries; `--remove-legacy` removes only the old entries the file now covers. Entries nobody owned get `decided_by: unknown`, which the decision shows as needing a person. See [Suppressions](https://keryn.dev/docs/guides/suppressions/) for the older forms.

## 6. Export OpenVEX

```sh
keryn export --vex vex.json .
```

`vex.json` is an OpenVEX 0.2.0 document of your answers: the status and justification pass through, the reason becomes the impact or action statement, the rule id is the vulnerability name, and an accepted risk is `affected` with who accepted it and until when. The product is `--product`, else the git remote as a purl, else `pkg:generic/<folder name>`. The [evidence pack](https://keryn.dev/docs/guides/evidence/) carries the same file.

## 7. Open issues for what is held

```sh
keryn decide export . --github example/app --dry-run
```

`decide export` opens one issue per chain or chokepoint of the trust model (findings on no chain: one per rule and directory), listing the findings, the edge, the proof level, the coverage and each finding's decision status. `--dry-run` prints the requests as JSON and uses no token and no network. A real run reads `GITHUB_TOKEN` or `GITLAB_TOKEN` from the environment (there is no flag for it), searches the tracker for each issue's `keryn:issue` marker first, and creates nothing that already exists or that an answer already tickets. The new issue's address becomes `ticket` on the answers; `--record` also adds `under_investigation` answers for findings without one, signed with your git email. Use `--gitlab <group/project>` for GitLab, `--gitlab-url` for a self-managed instance and `--github-url` for GitHub Enterprise.

Closing an issue never changes an answer. If per-finding alerts are all you need, use the SARIF file the scan writes instead: your pipeline's own step can send it to code scanning (Keryn never uploads it; see the [CI guide](https://keryn.dev/docs/guides/ci/)). Issues are for chains.

## In Keryn Web

After a scan, **Release decision** in the scan results opens the Decision Desk (`#/decide`). It computes the same label as `keryn decide` with the same function, and it pushes nothing.

- The label, then each Hold with its chain edge and proof level, and the accepted risks with who accepted them and until when.
- **Proposed by triage**: [triage](https://keryn.dev/docs/guides/triage/) verdicts (upheld, refuted, needs context, unsupported, declined) waiting for a person. A verdict is a suggestion and changes nothing. Only **Record decision** turns it into an answer: the form asks for the answer, the reason, an optional ticket and **Decided by**, a name you type, and **Add to decisions.yml** puts it in this tab's draft.
- **Coverage** and scope, as `.keryn/scope.yml` declares them.
- **Export issues**: one issue per chain of open Holds, in GitHub or GitLab. It shows the issues it would create before it sends anything, and sends only when you click, with the token of the connector you set up in Settings.
- **Save and sign**: **Save decisions.yml** downloads the file for you to copy to `.keryn/decisions.yml` and commit. The page does not sign. A signature is `keryn decide sign` in the repository, which records the git identity, is refused in CI and cannot sign as another name.

A scan of a zip or a repository link has no folder to read `.keryn/` files from, so **Open .keryn files** reads `decisions.yml`, `scope.yml`, `releases.jsonl` or `policy.yml` that you pick, in the tab. When the trust analysis cannot run, a Hold names its file and rule instead of a chain edge, and the page says so. The **Reports** menu's hand-off reports read the same files; see [controls, posture and hand-off reports](https://keryn.dev/docs/guides/controls-and-posture/#3-write-a-hand-off-report).

> **Note: In the next release**
> The CLI that is built and shipped now carries the trust-model engine. Before that fix, outside a source checkout, `keryn decide` could not run the trust analysis, so its Holds named `file:line -> rule` and not the chain edge.

## In CI

```yaml
- run: keryn scan . --fail-on error --sarif keryn.sarif
```

No change is needed: with `.keryn/decisions.yml` in the repository, the scan's exit code follows the decision (Hold fails the job). The [CI guide](https://keryn.dev/docs/guides/ci/) lists the exit codes.
