ci

Continuous Integration

The gate is .github/workflows/ci.yml; read it for the step list. It is both the PR check and a reusable workflow: release.yml's gate job calls it, so every push to main is validated before a tag is cut (release.mdc). Deploy: cd.mdc. This rule loads with every workflow, so its expression-context, script, and hardening rules apply to all of them (install and telemetry: where a workflow installs or runs the tools).

Expression contexts - read before touching env:

Workflow-level env: may reference only github, secrets, inputs, vars; job-level env: adds needs, strategy, matrix; runner, job, steps, and env are step-level only. An unavailable context is a validation error: the file stops parsing, GitHub reports the run under the file path instead of the workflow name, and zero jobs execute - it never degrades to an empty string (this once left ci.yml and cd.yml unparseable for 14 pushes). Anything needing $RUNNER_TEMP goes through a step:

- run: echo "NODE_COMPILE_CACHE=$RUNNER_TEMP/node-compile-cache" >> "$GITHUB_ENV"

Invariants

• Triggers: pull_request, workflow_call, workflow_dispatch. No push: - release.yml's gate covers pushes to main, so a commit is never checked twice.
• The required check is the job name Lint, typecheck, test, and build (the main ruleset, strict up-to-date): renaming the ci job leaves every PR waiting on a check that never reports.
• Parity is about the kinds of checks, not the mechanism: change both sides when adding or renaming a gate (deps:format:check exists because both call it by name). Locally pnpm run ci is pnpm run types, pnpm run boundaries, one turbo run of the //# root tasks plus check-types test build deploy:check with --continue=dependencies-successful, then pnpm run audit; here the same checks are separate parallel: steps calling bare pnpm run scripts. The local && chain is deliberately serial (types before type-aware lint, boundaries a cheap fail-fast pre-gate, audit a success-gated network tail); a parallel-sections rewrite was rejected to keep the gate zero-dependency. Never route the workflow through the //# tasks: a root task's default inputs span the repo, so under futureFlags.affectedUsingTaskInputs it would always be affected and defeat --affected.
• Scope by event: --affected on pull_request only, the full graph on workflow_call / workflow_dispatch (a release validates everything), expressed as two if:-gated steps - never interpolate the flag into a run: body. The dependency audit is pull_request-only for the inverse reason: the advisory DB changes daily, so an auditing release gate is not a pure function of the commit (local pnpm run ci still audits).
• The Changesets step is pull_request-only, like the audit: release:check diffs against origin/main, so the release gate has nothing to check. Locally ci, ci:agent, and ci:sandbox run it as //#release:check; ci:affected does not, since mid-task a changeset is not due yet. CHANGESET_ALLOW_MAJOR reads the release:major label from the event payload, and label events start no CI run, so adding the label takes a re-run of the job. The step also gets GITHUB_TOKEN (the job's contents: read) to read the base pnpm-workspace.yaml through the API. CHANGESET_SKIP_RUNTIME_DEPENDENCIES is set only on a Dependabot PR when CHANGESET_BOT_TOKEN is absent (release.mdc).
• No TURBO_SCM_BASE: on pull_request turbo infers the base from GitHub Actions, and futureFlags.githubActionsRemoteBaseRefFallback resolves it to origin/<base_ref> (checkout creates only remote-tracking refs). Never set it off PRs: github.event.before is all-zeros on a new branch, which silently degrades --affected to "everything changed". Keep fetch-depth: 0 + filter: blob:none.
• One job, with the parallel: step keyword (GA 2026-06-25, alongside background / wait / wait-all / cancel) for OXC (lint:ci, pinned to --format=github for PR annotations, and format), boundaries, syncpack, and zizmor; Knip is diagnostic only, never a step here or in pnpm run ci (quality-report.mdc). A parallel: list item takes no sibling keys. At most 10 background steps run at once and a PR runs 9, so an eleventh item would queue behind the others. The "Generate cf types" step (pnpm run types) runs before parallel:: type-aware lint needs the gitignored types, and the parallel turbo step, their only other producer, is --affected on PRs. There is no types-drift step (nothing generated is committed). check-types test build deploy:check is a single turbo run --continue=dependencies-successful at default concurrency (no override in turbo.json), so one run reports every package's failures.
• The deploy dry-run is the deploy:check task (cf deploy --prebuilt --mode production --dry-run per app) inside that single run, never a step after the join: turbo run deploy -- --dry-run hashes the pass-through args into every task of the graph, so the whole app build re-ran uncached. It depends on build only, and with --prebuilt needs neither token nor account ID, so the job gets no Cloudflare variables. ci:sandbox drops it with build: cf also stats the app's .env, which the agent sandbox denies (EPERM), and SKIP_ENV_FILES does not reach cf deploy.
• The release PR's check comes from a dispatched run: GitHub holds the pull_request runs of a github-actions[bot] PR at action_required until a writer approves them, so release.yml's version job runs gh workflow run ci.yml --ref changeset-release/main; a dispatch is exempt, and its run reports the bare job name on the PR head. The job-level if still skips an approved pull_request run of that PR, whose release:check would fail on the changesets the PR consumes. It is bound to head_ref == 'changeset-release/main' and author github-actions[bot]: a prefix match would let any PR skip the required check by naming its branch, and a pull_request branches-ignore filters the base branch, so it cannot express this.
• Step bodies longer than a few lines are scripts under .github/actions/<concern>/ (cd/, changesets/, previews/, quality/, release/; shared modules in lib/), not inline YAML. Invoke with bash <path>, wire inputs through step-level env:, open each script with set -euo pipefail, and fail fast on missing input (:? guards or an explicit check). Short steps stay inline.
• Install, in every workflow that installs: pnpm install --frozen-lockfile after pnpm/setup with install: false; Node runtime: node@26, matching root engines.
• Only ci.yml saves the pnpm store cache: actions/cache keyed on hashFiles('pnpm-lock.yaml'), never pnpm/setup's cache: true, whose key includes the run id and saved a new ~300 MB entry on every job. quality.yml's analyze job and changeset-pr-status.yml's pr-status job restore the same key read-only with actions/cache/restore (quality-report.mdc). Jobs holding a write token or Cloudflare credentials (version, CD, Previews) restore no cache: defense in depth, since cache scoping already keeps PR entries away from main.
• Remote cache: job env wires TURBO_TOKEN, TURBO_TEAM, and TURBO_REMOTE_CACHE_SIGNATURE_KEY (repo secret, >= 32 bytes, the same value as local machines; turbo.json enables remoteCache.signature + longerSignatureKey). workflow_call declares those secrets explicitly so the release gate never receives Cloudflare credentials; never secrets: inherit. TURBO_CACHE is local:rw,remote:rw on pull_request and local:rw,remote:w everywhere else: signing checks integrity, not trust, and same-repo PR runs hold both token and key, so a PR could upload an entry the release gate would replay as a passing check-types / test / build; write-only makes the gate run the full graph fresh and publish trusted artifacts. CD has no Turbo token at all. envMode is strict: a workflow env: value reaches a turbo task only if turbo.json lists it in env / passThroughEnv.
• Hardening, every workflow: every uses: is a full-length commit SHA with a # vX.Y.Z comment; actions/checkout sets persist-credentials: false; workflow permissions: {} with per-job re-grants (ci.yml: contents: read only - artifact upload and actions/cache use the runner's runtime token, not GITHUB_TOKEN); a same-repo uses: is $/<path> (this repository at the running commit, no checkout needed), never ./<path> - Dependabot ignores both; runners ubuntu-24.04, never ubuntu-latest. A workflow that runs turbo, cf, or Wrangler turns telemetry off at workflow env: (DO_NOT_TRACK covers cf; CF_SEND_TELEMETRY: "false" beside WRANGLER_SEND_METRICS).
• cancel-in-progress only on pull_request. Never interpolate github.ref_name into script bodies. No production or Cloudflare secrets in this workflow (CD only).
• Never add scanners "for completeness" without a concrete threat and owner. zizmor (the Workflow security step) has both: workflow edits, often agent-written, that bring an unpinned or impostor pin, a # vX.Y.Z comment not matching its SHA, template injection, or permission creep; the owner is the /.github/ CODEOWNERS entry. It is pull_request-only like the audit, since its online audits query the GitHub API, and CI-only (no Node distribution): reproduce with uvx zizmor . when uv is available. Fix a finding; an unavoidable one gets an inline # zizmor: ignore[<audit>] naming why.