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

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 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)

1. tawa deploy builds and deploys to sandbox (full pipeline)
2. 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)
3. 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

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

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