Skip to main content

The loop in CI

Every merge changes source content, and its translations, terms and voice checks fall behind. CI can catch them up on every change or on a schedule with the kapi loop. Items a machine cannot decide wait for review in the team's review session on the server, and the ship gate protects releases. An ordinary build passes while target languages are behind.

On a project connected to a Bowrain server, a CI run of kapi up executes on the server venue. The job pushes the drift, the server runs the loop with the organization's AI keys, shared content memory and terms, and the results come back to the working tree. The runner holds a server token and no provider keys.

The sections below list the CI surfaces and the exit codes they share. The kapi site has the step-by-step walkthroughs for scheduling, gating and cost reporting on GitHub and GitLab: The kapi loop in CI.

Your pipeline produceskapi-action · kapi-components · ghcr imagea merge or a schedule tickkapi up: the loop runs on the servera PR/MR with the run reportYour pipeline gateskapi check --shipa merge request opensthe bound gates runexit 3 blocks the mergeNo pipelineforge connector · Bowrain GitHub Appa push webhook reaches the serverthe server re-ingests and convergesone PR/MR, updated in place

Produce and gate from your own CI, or let the server do both with no pipeline at all.

The contract​

A pipeline needs three commands and their exit codes:

CommandRoleExit behavior
kapi statusObserve: per-locale coverage and gate standingAlways 0: behind is pending work, not an error
kapi upProduce: runs the kapi loop0 whether the run caught everything up, left work waiting for review, or went on after the event stream ended early; non-zero when the run broke or its outcome is unknown
kapi check --shipEnforce: the release bar0 pass, 3 gate unmet, 4 a gate did not run, 1 operational error

Work waiting for review exits 0. Add the gate to merge-request pipelines and a quality regression cannot merge. Day-to-day drift goes to review, and builds keep passing.

The surfaces​

SurfaceHow it runsGuide
GitHub Actionssetup-kapi installs the CLI (the bowrain plugin included by default); kapi-action runs kapi up and reports what changed, and a step of your own commits it or opens a pull request. The reusable kapi-workflows (up.yml@v1, gate.yml@v1) compose both into one-line jobsGitHub Actions
GitLab CIkapi-components from the CI/CD Catalog: up runs kapi up and reports what changed, and with deliver: mr opens a merge request; check gates merge-request pipelinesGitLab CI
Any container runnerghcr.io/neokapi/kapi (cosign-signed; the server-sync plugin is preinstalled, so kapi up / push / pull work out of the box) and the CLI directly; the exit codes above are the contractthis page
No pipelineThe forge connector / Bowrain GitHub App: the server converges on every push to the tracked branch and delivers the results back as one PR/MRThe Bowrain GitHub App

Which to use when​

  • You own the repository's CI and want control over triggers, delivery and gating: use kapi-action on GitHub or kapi-components on GitLab. Each job is an ordinary pipeline step you can shape.
  • You want minimal setup on GitHub: the reusable workflows give you the whole produce-and-deliver or gate job as a single uses: line.
  • Nobody owns the repository's CI, as in a docs, marketing or content repository, or you want no configuration in the repository: connect it server-side with the forge connector or the Bowrain GitHub App. The server catches up on every push and delivers a pull request back.

Authenticating a runner​

Mint a CI token once, from an authenticated machine:

kapi auth login
kapi auth token create --name "ci" --expire-days 90

The token (bwt_…) is shown once, so store it as a CI secret right away. On the runner, BOWRAIN_AUTH_TOKEN carries the credential, and the CLI checks it before any stored login:

BOWRAIN_AUTH_TOKEN=bwt_...
BOWRAIN_SERVER_URL=https://bowrain.example.com   # self-hosted only

You need BOWRAIN_SERVER_URL only for a self-hosted server. The hosted service (https://app.bowrain.cloud) is the built-in default, and project commands (kapi up, push, pull, check) read the server from the checked-out recipe's bowrain: block. On GitHub Actions, setup-kapi's auth-token and server inputs export exactly these two variables. On GitLab, set them as masked CI/CD variables. List and revoke tokens with kapi auth token list and kapi auth token delete.

What a job needs beyond the server token depends on its venue:

  • Server venue (a connected project): nothing. The server holds the AI keys; the job only pushes, watches, and pulls.
  • Local venue (kapi up --local, or a project with no bowrain: block): the loop runs inside the job and needs a provider key, for example ANTHROPIC_API_KEY, as a CI secret.
  • Gate-only jobs: kapi check --ship reads the working tree and needs no AI keys; when the gate enforces governed terms, the job runs kapi pull first and needs the server token. See Gate governed terms in CI.

Next​