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 run check (lint + type-check across all workspaces)
2. Backend Tests — pnpm run test in 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 — Deploys CDK stack (Lambda, API Gateway, DynamoDB, Cognito, CloudFront)
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.

Post-Deploy Hooks

After CDK deployment, the post-deploy.hook.ts script:

1. Publishes environment config JSON to S3 (used by frontend for environment switching)
2. Seeds ephemeral environments (copies users and DynamoDB data from integration)

Note: Manual API calls can be made via the Scalar interactive docs (/docs/viewer) or by running the auto-generated tests in 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 cdk deploy via the infra package
6. After CDK completes, post-deploy.hook.ts publishes environment config to S3
7. frontend-upload syncs the built assets to S3 and invalidates the CloudFront cache
8. publish-docs generates and publishes Scalar documentation with the latest API spec

For PR environments, the same pipeline runs with environment: prNNNN and environment-type: ephemeral, 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.