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 across affected workspaces)
2. Backend Tests — pnpm run test in apps/backend (with coverage)
3. 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. Each environment has its own Scalar project and custom domain: production at monorepo-starter-docs.wseng.rp.devfactory.com, integration at monorepo-starter-docs-int.wseng.rp.devfactory.com. 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 infrastructure job runs pnpm run deploy:<type> from apps/infra/, which invokes orchestrate-deploy.script.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
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)
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., Postman API sync)
   • Seeds ephemeral environments (copies users and DynamoDB data from integration)

Destroy Orchestration

When a PR is closed, destroy-ephemeral.yml runs pnpm run destroy:ephemeral from apps/infra/, which invokes orchestrate-destroy.script.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., deletes Postman environment and collection)
   • 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 main
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 --env integration

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

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

Accessing Deployed Environments

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