CI/CD & Environments

This guide covers the deployment pipeline, environment types, and automation workflows.

Environments

The monorepo supports three environment types:

Environment Differences

CI/CD Workflows

Deployment Workflows

Verification Workflow (verify.yml)

Runs on every PR (ready for review / synchronize):

1. Lint — pnpm check --affected (lint + type-check + format across affected workspaces)
2. Unit Tests — pnpm test across workspaces (with coverage)
3. DB Integration Tests — backend repository tests against a Postgres service container
4. Deployability — runs the domain/cert/quota preflight (preflightCustomDomain) then cdk synth for the PR's ephemeral stack, via deployability.orchestrator.ts. This catches CDK synthesis errors and deploy-invariant violations on the PR, so a green pipeline means "safe to deploy," not just "compiles and passes unit tests." It reuses the deploy orchestrator's fail-fast opening but does not seed reservations, run hooks, or deploy; a synth error that only manifests once shared policy refs are present is not caught here.
5. JIRA Ticket Check — Validates PR title/branch naming

Deployment Pipeline (base-deploy.yml)

The reusable deployment workflow runs these jobs:

frontend-build ──┐
                  ├──► frontend-upload
infrastructure ──┘
     │
     └──► publish-docs (production + integration only)

1. frontend-build — Installs deps, builds Vite app, uploads artifact
2. infrastructure — Runs the deploy orchestration script (see Deploy Orchestration below)
3. frontend-upload — Downloads build artifact, syncs to S3, invalidates CloudFront
4. publish-docs — Publishes Scalar documentation (production and integration only)

Docs Publishing: Documentation is published for production and integration only when the Scalar project exists for that environment. Integration serves at home-app-docs-int.dev.timeback.com. Production's intended host is home-app-docs.dev.timeback.com; that Scalar project is not provisioned on this bootstrap ticket, so the production docs URL does not serve yet. The API reference automatically points to the environment's own API, so reviewers can test endpoints directly from the docs. Ephemeral (PR) environments do not publish docs.

Deploy Orchestration

The PR-time Deployability check (in verify.yml) reuses this orchestration's fail-fast opening — the preflight plus cdk synth — without the seed, deploy, and hook steps, so synth failures surface on the PR instead of waiting for a deploy cycle.

The infrastructure job runs pnpm run deploy:<type> from apps/infra/, which invokes deploy.orchestrator.ts. This orchestrator runs the full deploy lifecycle in a single process:

1. Seed reservations — provisions shared account-level resources (CloudFront origin request policies) and writes SSM reservations to protect them from concurrent cleanup
2. Synth — runs cdk synth to produce the CloudFormation template (separate step because pre-deploy reads the synthesized template)
3. Pre-deploy (pre-deploy.hook.ts) — imports orphaned CloudWatch log groups so CDK can adopt them
4. CDK deploy — applies the CloudFormation changeset (Lambda, API Gateway, DynamoDB, Cognito, CloudFront). Non-ephemeral frontends may gain a Mixpanel /events/mp* behavior when synth has the Mixpanel origin-request-policy ref, and a Sentry /events/st* behavior when synth reads SENTRY_DSN from that deploy's secret (deploy-integration.yml uses the integration secret; deploy-production.yml uses the production secret). Ephemeral PR stacks omit those behaviors by design (resolveFrontendAnalyticsProxyProps).
5. Post-deploy (post-deploy.hook.ts):
   • Publishes environment config JSON to S3 (used by frontend for environment switching)
   • Runs optional external integrations via the integration registry (e.g., Slack notifications, Datadog dashboard upserts)
   • Seeds ephemeral environments (copies users and DynamoDB data from integration)
   • Seeds the API and E2E test users (ephemeral and integration; never production) and stores their credentials in SSM, where pnpm script update-env and the post-deploy test jobs pick them up

Postgres Database Provisioning

Each environment uses a database named tb_home_app_<env> on the product-owned Aurora cluster tb-home-app-dev. The CDK stack does not create RDS. The operator script pnpm script provision-environment --action provision creates the cluster. The migration runner creates each environment database with ensureDatabaseExists on first migrate.

• Ephemeral and integration: first migrate creates tb_home_app_<env> in-VPC.
• Production: provision a production cluster in a later ticket. This bootstrap writes a production secret without DB_* keys.

Destroy Orchestration

When a PR is closed, destroy-ephemeral.yml runs pnpm run destroy:ephemeral from apps/infra/, which invokes destroy.orchestrator.ts:

1. Pre-destroy (pre-destroy.hook.ts) — runs any pre-destroy validation
2. CDK destroy — tears down the CloudFormation stack
3. Post-destroy (post-destroy.hook.ts):
   • Deletes S3 environment configs
   • Removes SSM parameters
   • Cleans up orphaned CloudWatch log groups from CDK custom resources
   • Runs optional integration cleanup (e.g., revokes external resources registered by integrations)
   • Releases and sweeps SSM reservations for shared resources

Post-destroy is intentionally skipped when CDK destroy fails — the stack still exists, so cleaning up reservations or shared policies would be incorrect. On failure, the workflow opens a GitHub issue for manual intervention.

Note: Manual API calls can be made via the Scalar interactive docs (/docs/viewer) or by running the auto-generated tests in packages/api-tests/.

Automation Workflows

Deployment Flow (End-to-End)

A typical integration deployment follows this sequence:

1. Developer merges a PR into master
2. deploy-integration.yml triggers automatically
3. It calls base-deploy.yml with environment: integration
4. frontend-build compiles the React app with Vite
5. infrastructure runs the deploy orchestration script (deploy:integration), which seeds account-level resources, synthesizes, runs pre-deploy hooks, deploys the CDK stack, and runs post-deploy hooks (environment config publish, integration sync)
6. frontend-upload syncs the built assets to S3 and invalidates the CloudFront cache
7. publish-docs generates and publishes Scalar documentation with the latest API spec

For PR environments, the same pipeline runs with environment: prNNNN (the environment type is derived automatically from the name), but the publish-docs job is skipped (docs are only published for production and integration).

Managing Environments

Syncing Local .env from a Deployed Environment

# From the integration environment
pnpm script update-env integration

# From a specific PR environment
pnpm script update-env 20

# Wait for a stack that is still deploying
pnpm script update-env integration --wait

All also accept the target via --environment (aliases: --env, --pr).

Accessing Deployed Environments

Ephemeral environment URLs are output by the deploy step and posted as a PR comment.