Deployment Pipeline

This page documents the environments, CI/CD pipeline, and deployment process for Aero2.

Environments

Environment	URL	Database	Purpose
Local	http://localhost:8787	Local D1	Development
QA	https://qa.aero2.dev	aero2-qa	Staging and E2E tests
Production	https://aero2.dev	aero2	Live

Pull Request Workflow

When you push a branch and open a PR against main, CI runs automatically:

Lint -- Biome linting (npm run lint)
Build -- Compile and bundle (npm run build)
Unit Tests -- Vitest against local D1 (npm test)
Migration Separation -- Fails if PR mixes code and migration files

No deployment happens on PRs. Code is reviewed and merged to main.

Deployment Pipeline

When a PR is merged to main:

merge to main
    |
    v
1. Build & Test
   - Lint (Biome)
   - Build (Vite + Wrangler)
   - Unit tests (Vitest)
    |
    v
2. Deploy to QA
   - npx wrangler deploy --env qa
   - Verify health: GET https://qa.aero2.dev/health
    |
    v
3. E2E & API Tests
   - Playwright tests against live QA
   - API integration tests against live QA
    |
    v
4. Deploy to Production
   - npx wrangler deploy --env production
    |
    v
5. Health Check
   - GET https://aero2.dev/health
   - Auto-rollback on failure

Rollback

If production is broken after a deployment:

npx wrangler rollback --env production

This reverts to the previous Worker version. Note that database migrations cannot be automatically rolled back -- they must be handled separately.

NPM Scripts Reference

Script	Description
`npm run dev`	Start local development server
`npm run build`	Build for production
`npm run lint`	Run Biome linter
`npm run lint:fix`	Run Biome linter with auto-fix
`npm test`	Run unit tests (Vitest)
`npm run test:watch`	Run unit tests in watch mode
`npm run test:e2e`	Run Playwright E2E tests
`npm run test:api`	Run API integration tests
`npm run deploy:qa`	Deploy to QA (prefer CI)
`npm run deploy:prod`	Deploy to Production (prefer CI)
`npm run migrate:qa`	Apply migrations to QA database
`npm run migrate:prod`	Apply migrations to Production database
`npm run cf-typegen`	Generate TypeScript types from bindings

Secrets Management

Cloudflare Secrets (per environment)

Secrets are stored encrypted in Cloudflare and injected into the Worker at runtime:

# QA
wrangler secret put SECRET_NAME --env qa
 
# Production
wrangler secret put SECRET_NAME --env production

Required secrets:

Secret	Description
`MASTER_KEY`	Encryption key for secrets at rest (32+ character random string)
`BOOTSTRAP_ADMIN_EMAIL`	First user with this verified email gets admin role
`CF_API_TOKEN`	Cloudflare API token for custom hostname management
`GITHUB_CLIENT_ID`	GitHub OAuth app client ID
`GITHUB_CLIENT_SECRET`	GitHub OAuth app client secret
`GOOGLE_CLIENT_ID`	Google OAuth client ID (optional)
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret (optional)

CF_ZONE_ID is configured as an environment var in wrangler.json per environment (not as a secret).

GitHub Secrets (for CI/CD)

Set in the GitHub repository under Settings > Secrets and variables > Actions:

Secret	Description
`CF_API_TOKEN`	Cloudflare API token for deployments
`CF_ACCOUNT_ID`	Cloudflare account ID
`D1_QA_DATABASE_ID`	QA D1 database UUID
`D1_PROD_DATABASE_ID`	Production D1 database UUID

Troubleshooting

CI/CD Failures

# View recent workflow runs
gh run list
 
# View logs for a specific run
gh run view <run-id> --log-failed

Check Environment Health

curl https://qa.aero2.dev/health
curl https://aero2.dev/health

View Live Logs

npx wrangler tail --env qa
npx wrangler tail --env production

Quick Reference

Action	Command/Process
Start coding	`npm run dev`
Run tests locally	`npm test`
Open PR	Push branch, CI runs automatically
Deploy	Merge to main (automatic)
Apply migration	`npm run migrate:qa` then `npm run migrate:prod`
Rollback production	`npx wrangler rollback --env production`
Add secret	`wrangler secret put NAME --env ENV`
View logs	`npx wrangler tail --env ENV`