monorepo-template / ops

---
description: "GitHub Actions CD - called by release.yml after the tag, no push-tags trigger, Cloudflare versions upload then 100% promote, scoped API token on the production environment, GitHub-owned deployment record"
alwaysApply: false
globs: .github/workflows/cd.yml
---

# Continuous Deployment

The pipeline is [`.github/workflows/cd.yml`](../../../.github/workflows/cd.yml). Read it for the step list; a prose copy here would only drift. How a release reaches it: [`ops/release.mdc`](release.mdc). CI invariants: [`ops/ci.mdc`](ci.mdc). Human-facing secret/variable tables: the README deploy section. Wrangler secrets vs vars: [`backend/workers-config.mdc`](../backend/workers-config.mdc).

Weakening a deploy gate or shipping with missing credentials is covered by [`guardrails.mdc`](../core/guardrails.mdc) and is never the answer here either.

## Status

**CD is paused** until the `production` GitHub Environment secrets are configured. The pause is the repository variable `CD_ENABLED`, checked by `release.yml`'s `deploy` job - set it to `true` in the same act as adding the secrets. It deliberately does **not** live in this workflow: a job skipped inside a `workflow_call` target reports *success* to the caller, so a paused CD used to leave a green Release run with the tag already cut and nothing shipped. Gating at the caller makes the skip visible, and keeps `workflow_dispatch` usable for a manual redeploy.

## Trigger

- **`workflow_call` and `workflow_dispatch` only.** `release.yml` calls this workflow after it has cut the tag and confirmed it did not already exist; `workflow_dispatch` takes a `tag` input and is the redeploy/rollforward path.
- **There is no `push: tags:` trigger, and adding one is a regression.** The release tag is created with `GITHUB_TOKEN`, and events created by that token do not start workflow runs, so a tag trigger never fires (GitHub `GITHUB_TOKEN` docs; changesets/action#669, changesets/changesets#1545). Zero tags existed while that dead trigger was the only path.
- Do not deploy from `pull_request` or `pull_request_target` (the latter especially - base context plus untrusted checkout is a pwn pattern).
- **Concurrency is `cd-production`, `cancel-in-progress: false`, `queue: max`.** Cancelling would drop an in-flight ship; and with the default `queue: single` a third trigger replaces the pending one, silently losing that release.
- **Checkout uses `ref: refs/tags/${{ inputs.tag }}`** - the ship must match the tagged commit, not whatever the branch tip is at job start, and the qualified ref stops a same-named branch shadowing the tag. `Resolve release version` fails unless that commit is on `main` (compare API), so neither a dispatch nor a moved tag can ship an ungated commit. The tag must be exactly `vX.Y.Z`: a changesets pre-mode tag (`v1.0.0-next.0`) fails closed at `Resolve release version` instead of shipping @100%, and that red run is by design. `RELEASE_SHA` (the tagged commit) is what upload messages and Release notes record - `GITHUB_SHA` points at the dispatching ref on `workflow_dispatch` redeploys.
- **The build step is also the type gate: `pnpm turbo run check-types build --filter='./apps/*...'`.** `build` does not depend on `check-types` in `turbo.json`, and this job runs without the remote cache, so dropping `check-types` here would upload bundles that no step in this job type-checked. The trailing `...` pulls in the internal packages the apps ship; it only expands that way while `futureFlags.filterUsingTasks` stays off ([`core/turborepo.mdc`](../core/turborepo.mdc)).

## Auth and environment

- **The job declares `environment: {name: production, url: …}`.** Protection rules, required reviewers, and environment secrets belong there. Do not move Cloudflare credentials into unprotected repository secrets "for convenience".
- **Cloudflare credentials are never passed in by a caller.** `on.workflow_call` declares no `secrets:` at all - not even Turbo's, so the production build never restores remote-cache output a PR run could have planted; `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` are resolved from the `production` environment by the individual wrangler steps via step-level `env:` - install, build, and smoke never see them. Never switch the caller to `secrets: inherit`, and never lift the credentials back to job-level `env:`. A new wrangler step must copy the two-line credentials `env:` block - the `Require deploy inputs` gate only vouches for its own copy.
- **Both Cloudflare values are required** - the workflow fails closed if either is empty. Use a **scoped** Workers API token (Edit Cloudflare Workers, account-scoped), never a Global API Key, never a committed value. Secrets Store Edit only if the Worker binds Secrets Store.
- **`VITE_API_BASE_URL` is a repository/environment *variable*, not a secret** - public build-time config for `front-app`, and the `environment.url`. Still required; empty fails.
- **Wrangler auth in CI is non-interactive** via those env vars ([Cloudflare GitHub Actions guide](https://developers.cloudflare.com/workers/ci-cd/external-cicd/github-actions/)). Do not add `wrangler login` to CD.
- **No OIDC, and that is correct.** Cloudflare has no OIDC path here, and npm trusted publishing is npm-CLI-specific and irrelevant - nothing in this repo is published to npm. `id-token: write` would be privilege with no consumer.

## Versions upload, then promote

- **This repo does not use `wrangler deploy` or `cloudflare/wrangler-action` in CD.** Package scripts `upload` / `promote` call `wrangler versions upload` then `wrangler versions deploy …@100% --yes` against the workspace-pinned Wrangler, keeping the CLI identical to local and avoiding a second floating action pin.
- **Upload is machine-readable:** `WRANGLER_OUTPUT_FILE_PATH` captures JSON lines; CD parses `type === "version-upload"` for `version_id`. Do not replace that with scraping stdout - a per-app path is also what lets the uploads run concurrently without clobbering each other.
- **Keep `--strict`, and tag/message with the release version + `RELEASE_SHA` (the tagged commit).** Cloudflare: `--strict` makes upload/deploy more defensive in non-interactive CI - do not drop it to force green.
- **Traffic policy today is 100%.** Gradual percentages exist; do not add them without observability and a rollback runbook.
- **`versions upload` does not apply routes, custom domains, or cron triggers** ([deployment management](https://developers.cloudflare.com/workers/versions-and-deployments/deployment-management/)). When those land in `wrangler.jsonc`, also run `wrangler triggers deploy --env production` (comment beside the upload in `upload-versions.sh`).
- **The app set is discovered, never listed.** `.github/actions/lib/apps.mjs` reads every `apps/*/package.json`, so a new Worker ships by existing; `upload-versions.sh` and `promote-versions.sh` loop over it. It **fails closed** on an app missing an integer `monorepo.deployOrder`, and on two apps sharing one, instead of skipping or silently tiebreaking - a tag cut for a release that never shipped one of its Workers, or shipped them in an order nobody declared, is the failure this prevents.
- **Every app declares `monorepo.healthPath`** - the public probe path, or `null` when it has no public HTTP surface (RPC-only `worker-*`, `queue-*`). `apps.mjs` fails closed on an app that declares neither, because an app nobody declared a probe for ships to production unverified. `smoke-versions.sh` probes the app whose `monorepo.role` is `http-gateway` at `${VITE_API_BASE_URL}${healthPath}`; CD knows no other origin, so every other app with a non-null `healthPath` is named in a `::notice::` as promoted-but-unsmoked rather than passed over silently.
- **Promotes are sequential and ordered by `monorepo.deployOrder`.** Lower first: gateways before the SPAs that call them (`worker-api` 1, `front-app` 2). If a later promote fails while an earlier one is already live at 100%, production is split across two releases - `promote-versions.sh` names every already-promoted app and its `wrangler rollback --env production` command. Do not parallelize the promotes without handling that partial state, and declare a new app's position in its own `package.json` rather than reordering the loop.
- **Uploads run concurrently; only the promotes are ordered.** An upload changes no traffic, so nothing depends on its order and one failing cannot split production - that is the whole reason the two loops differ. `upload-versions.sh` backgrounds one `pnpm --filter` per app, each with its own `WRANGLER_OUTPUT_FILE_PATH` temp file, then `wait`s on every pid: an upload that fails does **not** abort its siblings, so the step reports every app that failed in one pass rather than only the first. The version-id table is written afterwards by walking the discovery order, never completion order, because `promote-versions.sh` reads it as the `deployOrder` contract. Each app's output is captured and replayed inside a `::group::` so concurrent streams do not interleave. Concurrency is unbounded - bound it here if an app count ever makes N simultaneous wrangler processes the constraint.

## Release and deployment records

- **The deployment record is created by GitHub**, because the job references an environment ("when a workflow job that references an environment runs, it creates a deployment object"). Do **not** re-create deployments through the REST API: an earlier version of this pipeline did, producing a duplicate record and marking GitHub's own one inactive.
- **Only the GitHub Release is ours to write** - created/updated in-workflow with `gh release create --verify-tag`, listing each deployed app's version id with its matching `apps/<app>/CHANGELOG.md` section when present.

## Same hardening as CI

SHA-pinned `uses:` with `# vX.Y.Z` comments; `persist-credentials: false` on checkout; workflow `permissions: {}` with per-job re-grants (`contents: write` for the Release, `deployments: write` for the environment record); runner `ubuntu-24.04`; frozen `pnpm install`; Node `24` via `pnpm/setup`; telemetry off. Step bodies live as scripts per the convention in [`ops/ci.mdc`](ci.mdc); the smoke probe now lives in `smoke-versions.sh` too, and the deploy-order coupling lives in each app's `monorepo.deployOrder` (above) rather than in step names. `$RUNNER_TEMP` only ever from a step - see the expression-context section in [`ops/ci.mdc`](ci.mdc), which is what broke this file once. Do not diverge "just for CD".

## What is deliberately not used

- **Workers Builds** - external GitHub Actions is the chosen path so CI and CD share one pipeline. Do not dual-enable Cloudflare Builds on the same production Workers. Branch Previews follow the same choice: `preview.yml` runs `wrangler preview`, not Workers Builds preview builds ([`ops/previews.mdc`](previews.mdc)).
- **Baking secrets into `wrangler.jsonc` `vars` or workflow YAML** - runtime secrets stay in Cloudflare; build secrets stay in GitHub Environments ([`workers-config.mdc`](../backend/workers-config.mdc)).
- **Deploying every green `main`** - only a newly created release tag deploys, gated on `create-release-tag`'s `created` output.

More agent context in louisbrulenaudet/monorepo-template

68 other files this repository gives its agents, the first 60 shown.