release

Releases

Changesets computes versions; the pipeline is .github/workflows/release.yml - read it for the job list. Human-facing "how do I": .changeset/README.md; writing a changeset: changesets.mdc. CI internals: ci.mdc; the deploy: cd.mdc.

Nothing is published to npm: every workspace is private: true, with no publishConfig and no .npmrc. A release is a git tag plus a Cloudflare Workers promote.

State machine

push to main ──► Release  (concurrency release-main, queue: max, never canceled)
  ├─ gate         ALWAYS. uses ci.yml (full graph, not --affected)
  ├─ select-mode  'version' | 'none'   ('publish' is unreachable here)
  ├─ mode == 'version' → version → open/update the "chore: release" PR
  │                                → dispatch ci.yml on changeset-release/main   [END]
  └─ mode != 'version' → tag (needs gate) → created? → deploy → uses cd.yml

Invariants

• gate runs on every push to main, in both modes. While a release PR is open the mode is always version, so a gate only on the release path would leave main unvalidated for that PR's whole life. Never move it under the mode != 'version' branch.
• The tag is the idempotency key. .github/actions/release/create-release-tag.sh skips when vX.Y.Z exists and reports created=false; deploy is gated on created == 'true', so re-running Release never re-deploys. The existence probe is three-way: 2xx skips, 404 creates, any other failure fails the job rather than guessing. Redeploy on purpose with cd.yml's workflow_dispatch and the tag.
• mode != 'version', not mode == 'publish': select-mode returns publish only when publishable packages exist, and all of ours are private, so the equality test would never fire. Load-bearing.
• select-mode installs first: with no pending changeset, as on every push after a release PR merges, it runs changeset publish-plan through require.resolve("@changesets/cli/bin.js") from the checkout, so without pnpm install the job fails and no tag is cut. Only the version branch works without the CLI, which is why a missing install stays hidden while a release PR is open. Every package is private and privatePackages.tag is false, so the plan is empty and the mode is none.
• privatePackages.tag: false is deliberate: changeset git-tag (v3's name for changeset tag) would emit one <app>@X.Y.Z per app, while the deploy keys on one shared vX.Y.Z, which create-release-tag.sh cuts instead.
• fixed: [["*"]] is the app set, resting on apps being unscoped: Changesets matches each fixed entry with picomatch against package names, and * does not cross /, so the group is exactly the unscoped workspaces (the apps), never an @repo/* package; a new app joins the shared version by existing. Nothing machine-checks the naming underneath (.syncpackrc.json's @repo/** group governs dependency specifiers, not workspace names; pnpm boundaries never reads a name), so naming.mdc keeps it by hand: an unscoped package under packages/ would silently join the group and bump to the app version.
• changelog names no repo: @changesets/changelog-github falls back to GITHUB_REPOSITORY, which Actions sets in the version job, so a repository created from the template links its own PRs and commits. Hard-coding the slug would point every derived changelog at this repository. changeset version runs only in CI, so nothing local needs it.
• privatePackages.version: true is load-bearing: v3 still defaults to {version: false, tag: false}, which would version nothing here. baseBranch: "main" restates the v3 default and stays because the bundled changesets/action sub-actions read the config with their own copy of @changesets/config.
• changedFilePatterns is the "what ships" list, matched with picomatch against paths relative to each package directory, so !*.md drops only top-level docs (README.md, AGENTS.md, CLAUDE.md), never a Markdown file under src/. It has no dot option: dotfiles never count, so a shipped dotfile (public/.well-known/*) needs its own pattern. Keep it aligned with the excludes of turbo's transit task.
• ignore: ["@repo/vitest-config"]: that package is test tooling only, so a change to it never needs a changeset. The config rule that dependents of an ignored package must be ignored too skips devDependency edges, so the apps stay versionable. Never ignore a package an app bundles: its changes would stop requiring a changeset.
• format stays at its auto default: Changesets runs oxfmt on every changeset and changelog it writes, so they pass format:check (the CLI writes ---\n\n--- for an empty changeset, which oxfmt rewrites). $schema pins the installed @changesets/config version; bump it with @changesets/cli.
• release:check (changesets/check.mjs, its logic checkChangesets in changesets/lib.mjs) wraps changeset status --since=origin/main --output, which exits 1 only when packages changed and no changeset changed since the merge base, and counts only tracked files (git diff), so a new changeset must be staged. Plain changeset status (release:status) counts every pending changeset, so it cannot tell whether the branch added one. The JSON plan feeds the lint (app-only names, title length, headings, major behind CHANGESET_ALLOW_MAJOR). Editing any pending changeset satisfies the presence half: coarse by design, the lint and review cover the rest.
• The changeset PR comment renders the gate's own result (changesets/comment.mjs): changeset-pr-status.yml runs checkChangesets, so the comment and the CI Changesets step never disagree, and changesets/action/pr-comment only posts it under the default marker. Never go back to changesets/action/pr-status: it takes no inputs, its add-a-changeset link prefills every changed workspace package (@repo/* and ignored ones included, which release:check rejects or Changesets refuses as a mixed changeset), an empty changeset reads as "included in the next version bump", and its no-changeset text assumes a non-blocking setup. The job installs because changeset status needs the CLI; it restores the pnpm store read-only (ci.mdc). changeset status exits 1 both for a missing changeset and for a crash, so a non-zero exit with no .changeset/*.md changed since the merge base reads as missing, anything else as unavailable: the renderer exits 1 after writing that body, and pr-comment runs on !cancelled(), so a failed run replaces the comment instead of leaving the previous commit's.
• Catalog bumps are checked separately (changesets/lib.mjs): pnpm-workspace.yaml belongs to no package, so Changesets never sees a catalog change. runtimeCatalogChanges diffs the catalog: / catalogs: specifiers against the merge base and keeps those an app lists under dependencies. A bump with no changeset in the branch fails the gate. In Actions the merge-base pnpm-workspace.yaml is read through the contents API with the job's read-only GITHUB_TOKEN, never git show: the blob:none checkout would fetch that blob lazily without credentials, which fails on a private repository such as one created from this template. Locally it is git show. For the same reason changesets/lib.mjs runs git and changeset status with diff.renames=false (through GIT_CONFIG_*): rename detection reads the blobs of every added/deleted pair, so a PR that renames files failed both release:check and the Release plan on could not fetch … from promisor remote. Lockfile-only refreshes of a direct dependency are not detected; add lockfile importer diffing if they start to matter.
• Dependabot changesets (dependabot-changesets.yml) commit one patch changeset per affected app as .changeset/dependabot-<PR>-<app>.md, reconciled to the desired state on every run, so a run that finds them current is a no-op. That no-op path needs no token, which matters because the run our own push triggers gets Actions secrets rather than Dependabot secrets.
  • The commit goes through GraphQL createCommitOnBranch with expectedHeadOid: GitHub signs it, and it fails rather than overwrite a newer push.
  • It uses the CHANGESET_BOT_TOKEN Dependabot secret (a fine-grained PAT, Contents: write), because Dependabot runs get a read-only GITHUB_TOKEN and a GITHUB_TOKEN push would start no CI run.
  • [dependabot skip] in the message keeps Dependabot rebasing the PR; a rebase drops the commit and the next run writes it again.
  • pull_request, never pull_request_target, and never pnpm install in that job: only git and Node run while the token is in the environment. With the secret unset it prints a notice and exits 0, and ci.yml sets CHANGESET_SKIP_RUNTIME_DEPENDENCIES=1 for that Dependabot PR, so the gate warns instead of failing: a project created from the template works with no setup, and its Dependabot bumps ship without a release note until someone adds one. The flag reads the Dependabot secret store, which is what a Dependabot-triggered run sees.
• The version job dispatches CI on the release branch (actions: write, beside the contents / pull-requests: write that changesets/action/version needs): the release PR is opened with GITHUB_TOKEN, so its pull_request runs wait for approval and the required check comes only from that dispatch (ci.mdc). While a release PR is open, every push to main therefore runs the full graph twice, as gate and as the dispatch.
• One contract comment on the release PR (release/comment-release-pr-contract.sh): changesets/action/version has no PR-body input, so its "published to npm automatically" description stays and the comment corrects it. gh pr comment --edit-last --create-if-none keeps one comment across every version re-run; changesets/action/pr-comment cannot be used here because it only targets the PR that triggered the run.
• The version PR branch is force-pushed, not accumulated: every push to main resets changeset-release/main from the tip, re-runs changeset version, and force-pushes one commit, so it is never behind or in conflict with main, and manual edits to it are destroyed.
• release.yml calls cd.yml directly because tags created with GITHUB_TOKEN start no workflow (cd.mdc); never "restore" a tag trigger.
• queue: max, not the default: with queue: single, a third push replaces the pending run and that release is silently dropped.