Deploy Pipeline

About

Covers the complete 15-step deployment pipeline: clone, config discovery, catalog parse, deploy gate, Dockerfile generation, Docker build/push, database provisioning, OAuth provisioning, dependency resolution, Helm deploy, DNS configuration, post-deploy health check, deploy-gated testing, and Koko registration. Includes all CLI commands and environment targets.

Skill Content

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

# Deploy Pipeline

## What this skill covers
The complete deployment lifecycle on Tawa — what happens when you run `tawa deploy` and how to use it.

## Deploy Command

```bash
# Deploy to sandbox (default)
tawa deploy

# Deploy to production
tawa deploy --prod

# Deploy to UAT
tawa deploy --uat

# Watch build progress in real-time
tawa deploy --prod --watch

# Check build status
tawa status

# View build logs
tawa logs --build <build-id>

# Stream live logs
tawa logs
```

## What Happens During Deploy

When you run `tawa deploy`, the builder executes this pipeline:

1. **Clone** — Clones your repo at the current commit (injects Forgejo token for private repos)
2. **Config Discovery** — Reads `.tawa.yaml` for monorepo settings (Dockerfile path, build context, Helm chart)
3. **Catalog Parse** — Parses `catalog-info.yaml` for framework, databases, routes, dependencies
4. **Deploy Gate** — Checks your org wallet has enough gas reserve (3 months of hosting cost)
5. **Dockerfile Generation** — Auto-generates a Dockerfile based on your framework (if none exists)
6. **Docker Build** — Builds the image, tagged with short commit SHA
7. **Docker Push** — Pushes to DigitalOcean container registry
8. **Database Provisioning** — Creates K8s secrets with connection strings (MONGODB_URI, REDIS_URL, NEO4J_URI)
9. **OAuth Provisioning** — Creates/updates Bio-ID OAuth client, injects BIO_CLIENT_ID and BIO_CLIENT_SECRET
10. **Dependency Resolution** — Resolves internal dependencies to K8s DNS URLs via Koko
11. **Helm Deploy** — Deploys to Kubernetes via Helm with all env vars injected
12. **DNS Configuration** — Creates/updates Cloudflare CNAME record
13. **Post-Deploy Health Check** — Verifies pods are running and healthy
14. **Deploy-Gated Tests** — If `spec.tests` is defined (catalog 0.5.0+), runs smoke tests via iec-test against the internal cluster URL
15. **Koko Registration** — Registers the service and routes in the service registry

## Build Status Flow

`queued` → `cloning` → `building` → `pushing` → `deploying` → `testing` → `completed`

If any step fails: → `failed`

You can retry a failed build: `tawa builds` then check logs.

## Environment Targets

| Flag | Namespace | URL Pattern |
|------|-----------|-------------|
| (default) | `{service}-sandbox` | `{service}.sandbox.tawa.insureco.io` |
| `--prod` | `{service}-prod` | `{service}.tawa.insureco.io` |
| `--uat` | `{service}-uat` | `{service}.uat.tawa.insureco.io` |

## Preflight Checks

Always run preflight before your first deploy:

```bash
tawa preflight
```

This validates:
- catalog-info.yaml syntax and required fields
- Health endpoint exists
- Git remote is accessible
- Framework annotation matches your project

## Monorepo Support

For monorepos, create a `.tawa.yaml` in the service subdirectory:

```yaml
# apps/my-service/.tawa.yaml
dockerfile: Dockerfile
buildContext: ../..
helmChart: ../../helm/my-service
```

## Key Facts
- Every deploy is idempotent — deploying again updates, never creates duplicates
- The builder auto-generates Dockerfiles — you rarely need to write one
- First deploy automatically registers the service in Koko
- Database and OAuth provisioning happen automatically
- DNS records are created/updated automatically via Cloudflare
- Build logs are available via `tawa logs --build <id>`

Install

Copy the skill content and save it to:

~/.claude/rules/deploy-pipeline.md

Details

Format

Rule

Category

deploy

Version

1.1.0

Tokens

~1,200

Updated

2026-02-24