# 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
```bash
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
```bash
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)
```bash
tawa approve                   # approve pending promotion
tawa approve --build <id>      # approve specific build
```

### View platform versions
```bash
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
```bash
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)

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

| 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

```bash
# 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