Roll back a release

“Roll back” means two different things in Kirimana, and conflating them is how teams get hurt. One is release-level rollback — reverting the contracts and transformations that are live in an environment. The other is control-plane rollback — reversing an upgrade of the Kirimana host itself. They use different verbs, have different reversibility guarantees, and this page keeps them apart.

Release-level rollback: forward-promote an earlier SHA

Kirimana’s release model is forward-only by design, and rollback is not an exception to that — it is an instance of it. To revert an environment to a previous state, you promote the earlier commit forward, exactly as you promoted the newer one.

First, find the SHA you want back. kiri release history lists promotions newest-first:

kiri release history --env prod --output json

Check out that commit, then plan and apply it into the environment:

git checkout <previous-sha>
kiri release plan --to prod
kiri release apply --to prod --tag v1.2.0

The plan shows you precisely what reverting will change — the diff between what is live now and the state you are rolling back to. Because the promotion is keyed on the git SHA, applying the earlier commit re-materialises the workspace to that earlier state. The release manifest’s release_sha now points at the older commit; the newer commit is still in git history, so this is a move along the commit graph, not a destruction of anything.

There is no separate kiri release rollback verb, and that is deliberate: a rollback that went through a distinct code path could drift from the apply path it is meant to reverse. Using the same plan / apply you use for every promotion means a rollback is reviewed, materialised, and audited identically to a roll-forward.

What is and isn’t reversible here

Reverting the release pointer is reversible: the contracts, generated models, and workspace objects Kirimana manages are re-materialised from the earlier commit. What that does not undo is data that has already been written under the newer contract. If a promotion widened a column, dropped rows, or ran an irreversible transformation, rolling the contract back does not un-write the data those runs produced. Treat schema-narrowing and destructive data operations as one-way: the release pointer moves back, the data does not travel with it. For that reason, validate a suspect promotion in staging before it reaches prod rather than relying on being able to undo it afterward.

Migration cutover: reconciliation is the gate, not a rollback

A migration cutover — moving a source system onto Databricks — is governed at the front by verification and reconciliation, not by a rollback at the back. kiri migrate verify runs the pre-deploy infrastructure checks and refuses to pass unless every one is green; kiri reconcile proves the migrated data matches the source row-for-row (PK, null-rate, date-bounds, SCD2 checks) before you sign off. The reconcile report can be produced in a locked mode that omits raw values for audit. Because a cutover writes real data into the target, the discipline is to gate hard on reconciliation before cutover — there is no verb that un-migrates a table once data is landed, so the reconcile signoff is the point of no return you plan around.

Control-plane rollback: kiri upgrade rollback

Upgrading the Kirimana host is a separate lifecycle with a genuine, supported rollback. The flow has two verbs. Before an upgrade, you capture a restore point:

kiri upgrade snapshot

snapshot captures a restorable pg_dump of the control plane’s own state store (Postgres) and records the pre-upgrade schema version into a JSON manifest beside the dump. That manifest is the artifact rollback restores.

If the upgrade goes wrong, reverse it:

kiri upgrade rollback

rollback reverses the Helm release to the prior chart revision, restores Postgres from the snapshot, then rewinds the schema migrations to the recorded pre-upgrade version. It shells out to the operator’s own helm and pg_dump / pg_restore — the same invocations the disaster-recovery scripts use — rather than re-implementing them, so what you rehearse in a restore drill is what runs in anger. Run kiri upgrade --check first: it is a read-only pre-flight that catches removed kiri.yml fields before they turn into a mid-upgrade failure.

The audit trail of a rollback

Nothing about a rollback is off the record. A release-level roll-forward-to-an-earlier-SHA is an ordinary promotion and shows up in kiri release history with its SHA and tag like any other. Every kiri upgrade run — --check, snapshot, and rollback — is wrapped in a trace so the operation is correlatable in the audit trail by its trace id, with the mutating snapshot and rollback paths recorded where correlation matters most. When someone asks “who rolled prod back, to what, and when?”, the answer is in the same audit surface that records every forward promotion.