CI/CD Runbook

CI/CD Runbook

Owner: Engineering Last reviewed: 2026-Q2

This runbook explains how Azure DevOps builds and deploys the repo.

Pipeline Entry Points

  • azuredevops/pipelines/api.yaml builds and deploys the backend.
  • azuredevops/pipelines/frontend.yaml builds and deploys the frontend.

Both pipelines trigger on dev, showcase, and main and are path-filtered to their app directories.

Branch To Environment Mapping

BranchVariable groupTagAzure subscriptionResource group
devdevdevworkopti-devdev-hsbm-rg
showcaseshowcaseshowcaseworkopti-devdev-hsbm-rg
mainprodprodworkopti-prodprod-gslm-rg
Pull requestshowcasevalidation onlyn/an/a

Backend Flow

  1. validate_changes checks for changes under backend/py/.
  2. templates/stages/docker-build.yaml builds the backend image from backend.
  3. Image repository is workopti; API tag is py.
  4. Images are pushed to workopti.azurecr.io through the workopti-acr service connection.
  5. Non-PR builds deploy through templates/stages/deploy-api.yaml.

Frontend Flow

  1. Pull requests install Node 22, run npm ci, then run npm run build.
  2. Non-PR builds use templates/stages/docker-frontend.yaml.
  3. Image repository is workopti-frontend.
  4. Deploy targets are environment-specific Azure Web Apps.
  5. Frontend deploys purge the configured Front Door/CDN endpoint and profile.

Promotion

  • Normal path: merge to dev, validate, promote to showcase, then promote to main when prod is enabled.
  • Promotion should include a short changelog, migration note, and manual validation note.
  • API and frontend can deploy independently, but API contract changes must keep OpenAPI/Orval compatibility in mind.

Rollback

  • Roll back by redeploying the previous known-good image tag for the affected app and environment.
  • If rollback follows a DB migration, check database-operations.md before downgrading or re-running migrations.
  • After rollback, verify health endpoints, login, board load, and the affected workflow.

Required Checks Before Deploy

  • Backend: route/service tests for changed behavior, migrations reviewed, env vars present.
  • Frontend: npm run build, npm run lint, generated clients refreshed when API changed.
  • Security-sensitive changes: second approval per how-we-work/code-review.md.
  • Docs updated when architecture, operations, API contract, or security behavior changes.

Failure Triage

  • Build failure: check dependency install, TypeScript/Python errors, Dockerfile changes, and path filters.
  • Push failure: check ACR service connection and image repository/tag.
  • Deploy failure: check Azure subscription, app service name, resource group, and container startup logs.
  • Frontend stale assets: check CDN purge stage and browser cache behavior.
InfrastructureEnvironment Variables