Artifact Promotion

Overview

Tawa uses artifact promotion to move builds through environments without rebuilding. Build once in sandbox, promote the same image to UAT, then to production.

Promotion Path

sandbox (full build + deploy)
  → UAT (image reuse, Helm upgrade only, ~1 min)
    → prod (image reuse + HIL approval required)

CLI Commands

Promote to next environment

tawa promote --to uat          # sandbox → UAT
tawa promote --to prod --yes   # UAT → prod (requires --yes for prod)
tawa promote --to uat --force  # bypass gate checks

Check deployment gates

tawa gates status              # show gate status for current environment
tawa gates status --env prod   # check prod gates
tawa gates status --json       # machine-readable output

Approve production promotion (HIL gate)

tawa approve                   # approve pending promotion
tawa approve --build <id>      # approve specific build

Approving a commit for a gated production deploy

Services enrolled in the deploy-approval gate need a sign-off on the exact commit before tawa deploy --prod will build. Approve the commit, then deploy:

tawa approve --commit 586badb --env prod   # short SHA (7+ hex chars) is fine
tawa deploy --prod

The builder resolves a short SHA to the full 40-character SHA at approval time, through Forgejo, and stores only the full SHA. tawa approve prints the commit it actually approved. An approval is single-use and expires after 24 hours.

You passed	Result
Full 40-char SHA	Stored as given
Unique 7–39 char prefix	Resolved to the full SHA and stored
Prefix that is unknown or ambiguous in the repo	Refused, `422 UNKNOWN_COMMIT` — pass the full SHA
Not 7–40 hex chars (`main`, `586bad`)	Refused, `400 INVALID_COMMIT`

If Forgejo cannot be asked (repo elsewhere, Forgejo down), the builder falls back to this service's build history: one matching built commit is accepted, more than one is refused with 422 AMBIGUOUS_COMMIT.

Fixed 2026-10-04 (iec-builder#256). The approve route used to store the SHA exactly as typed, while the gate matches the full SHA exactly. tawa approve --commit 586badb reported success and the next deploy was still BLOCKED: no valid, unconsumed approval. Short-SHA approvals made before the fix never match; re-approve, or let them expire.

View platform versions

tawa versions                  # list all version snapshots
tawa versions show v1.0.0      # show service matrix for a version
tawa versions diff v1.0.0 v1.1.0  # compare two versions

Check for breaking changes

tawa upgrade                   # show migration guide for your service
tawa upgrade --json            # machine-readable output

Deployment Gates

Gates are checks that must pass before promotion is allowed. They don't block deployment — only promotion.

Gate	What it checks	Required?
security	Dependency vulnerability scan	Yes
integration	Service-to-service connectivity	Yes
soak	Minimum time deployed (2 hours)	Yes
hil	Human-in-the-loop approval	Prod only
compliance	Septor audit trail + Wallet events	Yes

Gate behavior

Gates are evaluated at promotion time, not at deploy time
--force bypasses all gates (logged to Septor audit trail)
HIL approvals expire after 24 hours
All promotions are audited via Septor

How It Works (Technical)

tawa deploy builds and deploys to sandbox (full pipeline)
tawa promote --to uat calls builder API which:
- Finds the latest completed build in sandbox
- Verifies all gates pass (or --force)
- Creates a new Build record reusing the same Docker image
- Deploys to UAT namespace via Helm (no Docker build)
tawa promote --to prod --yes does the same UAT → prod, plus:
- Requires a valid HIL approval (from tawa approve)
- Records the promotion in Koko's promotion registry
- Emits promotion.completed Septor audit event

Septor Audit Events

Event	When	Data
`promotion.completed`	After successful promotion	serviceId, environments, imageTag, force flag
`promotion.approved`	After HIL approval	serviceId, buildId, approvedBy, expiresAt

PolicyEco Versions

A PolicyEco version is a snapshot of all platform services at specific image SHAs. Use versions to:

Pin your app to a known-good platform state
Detect breaking changes before upgrading
Track what changed between platform releases

# Target a specific platform version during local dev
tawa dev --platform-version v1.0.0

Best Practices

Always deploy to sandbox first — never promote from nothing
Let the soak gate do its job — don't --force just to go faster
Run tawa gates status before promoting to catch issues early
Use tawa upgrade to check for breaking changes before updating
HIL approvals are personal — the approver is recorded in the audit trail

Last updated: October 6, 2026