Releases
This is the intended delivery pipeline. Source checks and candidate builds exist; publication and environment promotion automation are pending.
This is the intended release pipeline for Kesita. Source checks and candidate image builds exist today; trusted publication, staging deployment and production promotion still need implementation. The status table at the end maps this design to the repository.
Delivery flow
Section titled “Delivery flow”Build a release once from a reviewed commit. Test its exact artifacts in staging, then promote those same artifacts to production. A release manifest identifies the source commit, every deployable image digest and the evidence used to accept it.
flowchart TB PR["Pull request"] --> CI["CI: code, contracts, schema and integration tests"] CI --> Review["Review and merge to main"] Review --> Build["Build release from exact merged SHA"] Build --> Verify["Scan images and verify build evidence"] Verify --> Registry["Publish immutable images and release manifest"] Registry --> Stage["Deploy staging by digest"] Stage --> Accept["Acceptance tests and observation"] Accept --> Receipt["Record successful staging receipt"] Receipt --> Approval["Approve exact release and receipt"] Approval --> Prod["Promote same image digests to production"] Prod --> Observe["Smoke tests, telemetry and deployment receipt"] Observe --> Complete["Mark release successful"]
A failed gate stops advancement. Fixing code creates a new candidate; it does not overwrite the failed candidate’s artifacts or evidence.
1. Pull-request CI
Section titled “1. Pull-request CI”Required checks establish that the change can be merged:
- Compile, lint, typecheck and run unit tests with pinned toolchains and locked dependencies.
- Check generated OpenAPI clients, database schema/query drift and environment contracts.
- Run the Hermit integration plan with real disposable dependencies and simulated paid providers. Validate discovery so an empty or skipped test set cannot pass as coverage.
- Build deployable images from the service-owned release catalog.
- For infrastructure changes, validate Terraform and run mocked tests. A live environment plan is a later deployment input.
Repository protection should require these results and review. Pull-request jobs receive no deployment credentials. Checks for a release must refer to its exact merged source SHA; results for an earlier branch revision are insufficient.
2. Build and publish a candidate
Section titled “2. Build and publish a candidate”A trusted workflow on main builds the release catalog for the deployment platform. It produces images, SBOMs, provenance and vulnerability results, then binds them to one immutable release manifest. Image scans must meet the team’s vulnerability policy; an exception needs an explicit owner and expiry.
The manifest records:
| Identity | Purpose |
|---|---|
| Release ID, repository and full source SHA | Identify the source being shipped |
| Workflow identity and build run | Identify the process that produced it |
| Image digest for every deployable | Select exact executable content |
| SBOM and provenance references | Inspect dependencies and verify origin |
| Product and legal schema fingerprints | Bind database expectations to the release |
| Integration and vulnerability evidence | Record why this candidate was accepted |
Publication must verify both content and trusted workflow identity. Structural validation of JSON alone cannot prove provenance. Store the manifest and evidence with immutable references in the release registry and retain previously deployed releases for recovery.
Environment-specific settings and secret references are supplied during deployment. If a frontend currently bakes an environment-specific value into its image, that must be resolved before the same artifact can move between environments. Staging-to-production promotion must not rebuild it.
3. Deploy and accept staging
Section titled “3. Deploy and accept staging”Publishing a candidate should trigger staging deployment. Serialize deployments to each environment so two releases cannot interleave migrations, revision changes or acceptance checks.
sequenceDiagram participant W as Deployment workflow participant R as Release registry participant S as Staging participant T as Acceptance checks W->>R: Fetch and verify pinned manifest and artifacts W->>S: Validate configuration, infrastructure and schema state W->>S: Run required schema setup under migrator identity W->>S: Deploy APIs, workers and frontend by digest S-->>W: Readiness and observed revisions W->>T: Exercise staging through real ingress and identity T-->>W: Results and observation evidence W->>R: Record receipt bound to this release and observed state
The deployment order follows dependencies: required infrastructure/configuration, database work, backend and worker revisions, then frontend traffic. Readiness must succeed before a revision serves traffic or admits work.
Staging acceptance should exercise login and tenant isolation, a representative task through the queue and worker, document ingestion/retrieval, legal search, and cancellation/recovery. Use synthetic staging data. Add bounded live-provider smoke calls to verify credentials and actual provider connectivity; Hermit’s simulated responses cannot establish that.
Compare observed image digests and database fingerprints with the manifest. Inspect error rate, latency, queue age, failed or uncertain operations and provider failures over an agreed observation window. Thresholds and budgets must be defined before the run. Persist a failed or partial receipt when deployment or acceptance fails; only a successful receipt makes the release eligible for promotion.
4. Promote to production
Section titled “4. Promote to production”Production promotion is a separate, protected action. Its review shows the release ID, source changes, staging results, infrastructure/configuration changes, schema impact and recovery plan.
Pin the release manifest and staging receipt before approval. After approval, fetch those exact objects again and verify their digests, trusted workflow identities and content binding. Do not resolve a moving “latest staging” reference at this point.
The production job uses its own environment identity and secrets, acquires the production deployment lock and deploys the same image digests. Environment configuration may differ, but the differences must be reviewed and recorded. Repeat readiness, a bounded production smoke test and telemetry observation before marking the release successful.
Infrastructure changes use a reviewed plan for the target environment and locked remote state. Keep infrastructure provisioning permissions separate from runtime deployment and registry publication. The private registry also requires a runner with network access; an OIDC identity alone does not provide connectivity.
Database and worker changes
Section titled “Database and worker changes”Kesita is prelaunch. Fresh disposable environments can install the clean product and legal baselines; the existing baseline installers are not an upgrade mechanism for a populated database. A fingerprint mismatch must stop deployment instead of triggering an automatic reset.
Before deploying a release that changes persistent state, explicitly choose whether the environment can be recreated or requires a reviewed data/schema change. That decision and any downtime belong in the release plan. Storage & indexes owns the data recovery and deletion obligations.
Worker revisions can outlive a deployment through durable work. Release automation must consult the worker recovery contract before stopping or replacing revisions. The rollout orchestration described here is target work.
Failed deployments and recovery
Section titled “Failed deployments and recovery”| Failure point | Required response |
|---|---|
| CI, build or artifact verification | Stop; no environment deployment |
| Staging deployment or acceptance | Record failure; block production promotion |
| Production before traffic/work admission | Stop activation; keep or restore the prior serving revision |
| Production after activation | Halt further rollout, stop affected admission if needed and inspect the recorded environment state |
| Schema or durable-work incompatibility | Use the reviewed recovery plan; an image rollback alone may be unsafe |
An application rollback redeploys a previous verified manifest by digest only when the current schema and durable work can support it. Otherwise repair forward or perform the planned restore. Never rebuild an old commit and assume it is the previously tested artifact. Record the recovery action and verify service health afterward.
Implementation status
Section titled “Implementation status”CI checks code, contracts and schemas, builds candidate images with SBOM and provenance artifacts, and validates Terraform without applying it. The release CLI can validate catalogs, manifests and promotion inputs. These checks prepare a candidate; they do not publish it to a trusted registry or prove that an environment accepted it.
The full Hermit integration run is not yet a CI gate. Trusted registry publication, vulnerability gating, staging deployment with acceptance receipts, and protected production promotion and recovery automation still need workflow implementation. Delivery infrastructure has definitions but is not established as deployed by those files alone.
The CLI’s manifest and receipt validators already name build-release.yml and deploy-release.yml as intended trusted workflows; those workflow files do not exist yet. Validation helpers do not deploy environments.
Inspect the existing catalog and commands with ./bin/kesita release catalog and ./bin/kesita release --help. Implement the missing pipeline in this order: required integration gate, trusted publication, staging acceptance, then protected production promotion and recovery.