Artifact Promotion

About

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

Skill Content

This is the raw markdown that gets installed as a Claude Code rule.

# 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

Install

Copy the skill content and save it to:

~/.claude/rules/tawa-artifact-promotion.md

Details

Format

Rule

Category

deploy

Version

1.0.28555

Tokens

~909

Updated

2026-06-24