proompteng Deployment
Overview
Production image delivery is automatic and single-writer:
main merge -> tested image build/publish -> Kargo Warehouse -> Freight -> exact automatic Stage promotion ->
Kargo copies the source commit and full digest/build metadata to kargo/<stage> -> Argo CD sync/health -> workload
rollout and live proof.
Repo-owned builders publish kargo-sha-<40> only after the final multi-architecture OCI index succeeds, with OCI
org.opencontainers.image.created set to the source commit's RFC3339 time and org.opencontainers.image.revision set
to its full SHA. Their Warehouses ignore legacy sha-* and mutable latest. External analysis uses publisher
latest only as a Digest-strategy discovery pointer and pins the immutable digest in Freight/manifests; external
bilig uses bare 40-hex/NewestBuild. Agents do not create or retag release tags.
Kargo is the promotion authority. Git remains the complete desired-state authority. Do not create a digest/SHA manifest
bump, release branch, deployment PR, release automerge, Image Updater change, manual Argo sync, or direct Kubernetes
deployment for a normal release. Kargo-owned kargo/<stage> branches are generated deployment state and are pushed
without a pull request; Argo Applications track those branches.
When to use
- You need to verify a source merge, image publication, Freight, Stage promotion, or workload rollout.
- You need to enroll a new image-backed application (see
docs/release-automation.md). - You need to recover a failed rollout by re-promoting a previously proven Freight.
Verify a promotion
Use explicit namespaces and read-only commands:
kubectl -n lab-delivery get project,warehouse,freight,stage
kubectl -n lab-delivery get warehouse/<warehouse> -o yaml
kubectl -n lab-delivery get freight/<freight> -o yaml
kubectl -n lab-delivery get stage/<stage> -o yaml
kubectl -n argocd get application/<application> -o jsonpath='{.status.sync.status}{"\n"}{.status.health.status}{"\n"}'
kubectl -n argocd get application/<application> -o jsonpath='{.spec.source.targetRevision}{"\n"}{.status.sync.revision}{"\n"}'
kubectl -n <workload-namespace> rollout status deployment/<deployment> --timeout=5m
kubectl -n <workload-namespace> get pods -l app.kubernetes.io/instance=<application> -o wide
Confirm the Freight digest, generated kargo/<stage> branch, Application target revision, running image ID, rollout,
and service-specific readiness/live check. Argo Synced and Healthy are necessary but do not prove that the new
workload is ready or that the service works.
Rollback and break-glass
For a failed promotion, fix the source-owned failure and re-promote a known-good Freight through Kargo. Kargo rewrites
and pushes the deployment branch; Argo reconciles it. Do not edit a live Deployment or manifest, run argocd app sync,
or make a deployment PR. A direct deployment is permitted only with explicit break-glass authorization recorded in the
incident; restore Kargo control afterward.
The Bayn exception remains in force: Bayn is not enrolled in a Kargo Warehouse or Stage. bayn-release activation and
source-lineage state govern strategy activation.
Development-only helpers
The repository contains service scripts that can build or mutate a local/isolated environment. They are not the
production image-promotion path and must not be used to bypass Kargo. See packages/scripts/README.md for their scope.
Resources
- Canonical flow and enrollment:
docs/release-automation.md - Reference runbook:
references/deploy-runbook.md - Checklist:
assets/deploy-checklist.md