Ship gates & CI

Goal: treat content quality like any other test. A ship gate is the project's release bar: coverage thresholds over the translation lifecycle plus the bound quality gates (voice, terminology, rule-based checks, staleness). kapi check --ship evaluates all of it in one shot and exits non-zero when a gate is unmet, so a regression never merges. Ordinary builds never fail on target drift; a language that is behind is pending work, and --ship is the explicit, opt-in enforcement point. The model is the kapi loop; this guide is the task. Needs a committed kapi project.

Desktop

The project view shows each locale's standing against its gate continuously: the same derivation check --ship enforces:

1. Read the gate cells. Each locale row shows coverage per lifecycle rung (translated, reviewed, signed-off) and whether the scope clears its gate.
2. Close the gap. Bring up to date produces what a machine can; a gate cell opens the Review queue for what needs a person.
3. Ship when green. When every scope clears its gate, the CI check below passes by construction.

▣

ScreenshotPending capture

The coverage grid with per-locale ship-gate cells, one scope green, one pending with the unmet threshold named.

View scene script ↗

Agent (Claude)

Ask for the standing, or for the fix:

Are we shippable in German? If not, get us there.

The assistant reads kapi status --json, runs kapi up for what a machine can close, walks you through the review worklist for what it can't, and confirms with kapi check --ship. With the Claude Code plugin installed, the Stop hook runs the gate automatically when Claude tries to finish; a failing gate keeps it working with the findings. See Use with Claude.

CLI

kapi check --ship runs the project's bound quality gates plus its ship/source coverage gates; with no file arguments it inspects the project's content across every target language:

kapi check --ship                 # the pre-release bar: exit 0 pass, 3 gate fail, 4 did not run
kapi check --ship --locale de     # scope the target-side gates to one locale
kapi check --ship --json          # structured result for a job summary

A gate that finds no content to check, or whose checks could not show they flag a known problem, did not run. It reports did_not_run with a did_not_run_cause and exits 4, even with --no-fail, so an empty scope never reads as a passing release.

The terminology gate runs wherever terms govern content in scope, whether the project defaults bind them or a profile that a collection's channel resolves to. Its coverage counts content no bound terms answer for as not_governed, and a governed target that could not be read as not_checked. When none of the governed content could be read, the gate did not run.

In GitHub Actions, install the CLI with the companion setup-kapi action and run the gate:

.github/workflows/ship-gate.yml

name: Ship gate
on:
  pull_request:
    paths: ["content/**", "src/locales/**"]
jobs:
  ship-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: neokapi/setup-kapi@v1
        with:
          version: "1.2.0"
      # Exits 3 (failing the job) when a voice, terminology, check,
      # staleness or coverage gate is unmet, and 4 when a gate did not run.
      - run: kapi check --ship

kapi finds the recipe by walking up from the working directory, so no project path is needed at the repo root. A reviewed threshold reads its decisions from the committed unit-state record under .kapi/state/ (see the project store): kapi commit those shards and include them in the PR, or the runner sees no approvals and a reviewed gate can't pass. For a targeted, file-level gate on named files (no project), use plain kapi check. If a CI job also produces translations (kapi up in a workflow), give it an API key via a secret env var; a Claude subscription sign-in is bound to your user and its usage window, so CI always uses a key.

On GitLab, the same gate is one include: the check component runs on merge-request pipelines, fails the pipeline on exit 3, and posts one threaded MR note with the findings:

.gitlab-ci.yml

include:
  - component: gitlab.com/neokapi/kapi-components/check@0.1.0

The full pipeline picture (catch up on a schedule, deliver a PR/MR, gate merges, report the cost of a change) is in The kapi loop in CI.

File checks vs project gates

Two bars, one command. A bare kapi check <files> gates the files you name: a checkset over their content, findings and a severity gate, no project needed; the test runner. kapi check --ship gates the project: coverage against the recipe's ship_gates: plus the bound quality gates, across every target language: the release bar. Use the first while content is being written, the second before it ships; see Check content like tests for the file-level half.

Next

• The kapi loop: gates, ladders, and the derived-state model.
• Tier gates per market: different review bars per locale, one enforcement job.
• Review & approve: raising the reviewed coverage a gate measures.
• Check content like tests: the file-level checkset and Report.