Skip to content

Releases

Target

This is the intended delivery pipeline. Source checks and candidate builds exist; publication and environment promotion automation are pending.

Code and tests

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.

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.

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.

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:

IdentityPurpose
Release ID, repository and full source SHAIdentify the source being shipped
Workflow identity and build runIdentify the process that produced it
Image digest for every deployableSelect exact executable content
SBOM and provenance referencesInspect dependencies and verify origin
Product and legal schema fingerprintsBind database expectations to the release
Integration and vulnerability evidenceRecord 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.

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.

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.

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.

Failure pointRequired response
CI, build or artifact verificationStop; no environment deployment
Staging deployment or acceptanceRecord failure; block production promotion
Production before traffic/work admissionStop activation; keep or restore the prior serving revision
Production after activationHalt further rollout, stop affected admission if needed and inspect the recorded environment state
Schema or durable-work incompatibilityUse 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.

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.