Skip to main content

​
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

BranchPurposeDeployment
mainShipping branchProduction deploy target
feature branchesIn-progress workPreview 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

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

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: 
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: 
# 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

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

Testing

Test and quality gates

Contributing

Development guidelines