> ## Documentation Index
> Fetch the complete documentation index at: https://docs-terra.withunify.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment Workflow

> Branch strategy, CI/CD gates, and releases for Terra

# Deployment Workflow

> Terra now uses a mainline release model: `main` is the source of truth, CI gates every change, and tags create human-readable GitHub releases.

## Branch and Environment Model

```mermaid theme={null}
flowchart LR
    PR["Feature Branch / PR"] --> CI["CI gates (typecheck + lint + tests + Terra smoke)"]
    CI --> Main["main"]
    Main --> Prod["Vercel production"]
    Main --> Tag["Create v* tag"]
    Tag --> Release["GitHub Release workflow"]
```

| Branch           | Purpose          | Deployment                  |
| ---------------- | ---------------- | --------------------------- |
| `main`           | Shipping branch  | Production deploy target    |
| feature branches | In-progress work | Preview deploys + PR checks |

## Required CI Gates

Terra CI (`.github/workflows/ci.yml`) enforces:

1. Build/typecheck
2. ESLint
3. Vitest suite
4. No skipped Terra Playwright directives (`check-terra-skipped-tests.mjs`)
5. Chromium public status smoke test

If any gate fails, do not merge.

## Daily Development Flow

```bash theme={null}
# Start from main
git checkout main
git pull origin main

# Create a short-lived feature branch
git checkout -b codex/my-change

# Work, commit, push
git add .
git commit -m "feat: ..."
git push -u origin codex/my-change

# Open PR to main
gh pr create --base main
```

After merge, verify production health checks (status page, queue health, webhook errors) before starting the next release ticket.

## Release Process (GitHub Releases)

Terra release automation lives in `.github/workflows/release.yml`.

### Option A: Tag push (most direct)

```bash theme={null}
git checkout main
git pull origin main
git tag v2026.2.22
git push origin v2026.2.22
```

If you need multiple releases on the same day, use a patch suffix:

```bash theme={null}
git tag v2026.2.22.1
git push origin v2026.2.22.1
```

### Option B: Manual workflow dispatch

Use **Actions → Release → Run workflow** and provide:

* `tag` (optional; auto-generates `vYYYY.M.D` if omitted)
  If `vYYYY.M.D` already exists, the workflow auto-selects `vYYYY.M.D.1`, `.2`, etc.
* `target` (defaults to `main`)
* `prerelease` (optional)

The workflow creates/pushes the tag if needed, then publishes a GitHub release with generated notes and appended plain-language summary context.

## Rollback

If a bad change lands on production:

```bash theme={null}
# Revert on main
git checkout main
git pull origin main
git revert <bad_commit_sha>
git push origin main
```

Then cut a new patch tag to document the rollback in release history.

## Quick Commands

| Task                        | Command                                                                                                          |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Update local main           | `git checkout main && git pull origin main`                                                                      |
| Push feature branch         | `git push -u origin codex/<name>`                                                                                |
| Open PR                     | `gh pr create --base main`                                                                                       |
| Run Terra tests locally     | `pnpm --dir apps/terra test`                                                                                     |
| Run Terra smoke E2E locally | `pnpm --dir apps/terra exec playwright test tests/status-lookup.spec.ts --project=chromium --grep "Smoke Tests"` |
| Cut release tag             | `git tag vYYYY.M.D && git push origin vYYYY.M.D` (or `vYYYY.M.D.N` for same-day patch releases)                  |

***

<CardGroup cols={2}>
  <Card title="Testing" icon="flask" href="/operations/testing">
    Test and quality gates
  </Card>

  <Card title="Contributing" icon="git-branch" href="/operations/contributing">
    Development guidelines
  </Card>
</CardGroup>