Skip to main content
T4 epic · devops / release engineering: time is a first-class citizen. The train holds with nika:wait until: (an absolute instant computed when the departure is signed, not a sleep), the gates’ duration is computed with nika:date op: diff, a human signs the departure, and the record lands in the journal whether the train left or not.

The job

Release day choreography: three gate checks run as one parallel wave (the version file matches the version you ship, the changelog has its section, the schema parses), jq folds them into one board, and an assert refuses departure on any red. The conductor signs with full information (« Green in 3 min · ship 1.4.0, departure window opens in 15m? »), the train holds until the window, ships only when armed, re-polls prod until it reports the new version, and after: { live: terminal } files the departure record either way.

The shape

The file

release-train.nika

How it works

1

until: is a hold, not a sleep

window adds inputs.hold_for to the moment the departure was signed (signed_at), and hold waits until: that instant, capped by timeout: 48h. An instant survives a restart where a duration: would start counting again, and computing it after the signature keeps it in the future: a literal timestamp fails NIKA-BUILTIN-WAIT-002 the day after it was written.
2

The human signs with full information

nika:date op: diff computes the gates’ wall time, and the nika:prompt message carries it: the conductor decides knowing how fresh the green is. A « no » skips signed_at, so nothing after it runs except the record.
3

The record always lands

ship runs only with --var depart=true. verify re-polls prod (retry × 5, exponential) until it reports the shipped version, the final assert refuses to claim success otherwise, and after: { live: terminal } emits the journal event with the REAL status, even on failure.

Constructs you just used

Run it

What it needs: A folder that holds VERSION, a CHANGELOG.md with a [<version>] heading, and schemas/workflow.schema.json (a JSON Schema with an $id): the three gates read them. No model and no key. The departure itself (--var depart=true) also needs ./scripts/release.sh and a live /version endpoint; an unarmed run never reaches either.
1

Rehearse it

The rehearsal brings its own release files, writes nothing in your folder and stops at the conductor gate, as a real run does. Before it runs, nika try names the hosts a step may reach: may reach: api.example.com — the mock replaces the model, not the network.
2

Get your own copy

Save the file above as release-train.nika. To try it outside a real release, create the three files its gates read:
3

Check it, then run it

A green board, a signed departure, a five-second hold, then no ship: depart is off, so ship is skipped and the run emits a release.train.departed event with departed: false. Without --answer, a terminal asks you at the conductor gate; a script pauses there (exit 4) and prints the --resume line.

Make it yours

  • Generate the notes on the same train: call Release notes as a child workflow between conductor and hold.
  • Canary first: duplicate ship/verify against staging, gate prod behind a second assert.
  • Move the window: inputs.hold_for sets how long after the signature it opens (15m by default), so --var hold_for=2h holds the train two hours after the conductor signs.

Back to all examples

The full gallery: four tiers, every construct taught by a real job.