ci(github): tag and publish a GitHub Release when the release PR merge

[7sharp9]

Overview

Closes #470, the last open part of #234 item 2

ShipIt delivered the version bump and the changelog section; it cannot produce release artifacts.

This adds .github/workflows/tag-release.yml, which fires when a ShipIt release PR merges and:

1. checks out the merge commit (pull_request.merge_commit_sha);
2. runs scripts/ReleaseNotes.fsx to get the version, tag and Release body;
3. creates an annotated v<version> tag on that commit;
4. publishes a GitHub Release with that version's CHANGELOG.md section, flagged pre-release for a SemVer pre-release version.

Both write steps are idempotent, so a re-run recovers rather than duplicating.

Further information

• Tag format: v-prefixed, so downstream workflows can filter on v*.
• Tag target: the merge commit on master, not ShipIt's chore: release commit on the reused release/master branch.
• Pre-release flag: derived from SemVer version, not from CHANGELOG.md front matter.
• Build output: none; the tag and changelog body are the release artifact.

Why not use ShipIt's trigger: github.event.head_commit.message is not reliable for merge commits. The workflow instead watches release/master, which works regardless of merge method.

Why not read the pre-release flag from the changelog: pre_release: describes the next release, so it can drift over time. Versioning.isPreRelease derives it from the actual version.

About #459: the tag and release are created with GITHUB_TOKEN, which does not trigger workflows. The Docker publish therefore has to be in the same workflow, or use workflow_dispatch/repository_dispatch, or a PAT/App token.

Why parse in a script instead of YAML: the same version logic is used by CI, backfill, and local dry runs. Keeping it in Versioning.fsx avoids version-resolution drift.

AI usage disclosure

Claude code was used to assemble the documentation and verify some logic for ShipIt's mechanism for release tags etc.

[greptile-apps]

Greptile Summary

This PR adds automation that turns merged ShipIt release PRs into annotated version tags and GitHub Releases, along with release-note extraction tooling and updated release-process documentation.

• Adds a pull-request-close workflow that tags the merge commit and publishes its changelog section.
• Centralizes version and changelog handling for release automation.
• Documents release triggers, pre-release handling, backfills, and downstream workflow constraints.

Confidence Score: 2/5

The PR should not merge until release jobs are restricted to genuine repository-owned ShipIt PRs and existing tags are validated against the intended merge commit.

The workflow can publish official artifacts for a merged non-ShipIt branch sharing the expected name, and its recovery path can publish a Release for an existing tag that points at the wrong revision.

Files Needing Attention: .github/workflows/tag-release.yml

Security Review

The release workflow authorizes publication using only the unqualified source branch name. A merged same-named branch from a fork or another non-ShipIt source can therefore invoke repository-write release automation. How this was verified: The job has contents: write permission and checks head.ref without checking head-repository identity, author, or the documented ShipIt label.

Important Files Changed

Filename	Overview
.github/workflows/tag-release.yml	Adds the release publication workflow, but its ShipIt identity gate and existing-tag recovery path can publish unintended or incorrectly targeted release artifacts.
DEVELOPMENT.md	Documents the new release workflow, its trigger, local preview commands, and downstream GITHUB_TOKEN limitation.
docs/mdr/design-history/0021-build-system-versioning-and-release.md	Amends the accepted release architecture with explicit tag-target, pre-release, backfill, and artifact decisions.
docs/mdr/design-history/0000-change-log.md	Records the ADR amendment in the design-history change log.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Pull request closed against master] --> B{Merged and head.ref equals release/master?}
  B -- No --> C[Skip workflow]
  B -- Yes --> D[Checkout merge_commit_sha]
  D --> E[Extract version and changelog section]
  E --> F{Tag name already exists?}
  F -- No --> G[Create and push annotated tag]
  F -- Yes --> H[Accept existing tag without target validation]
  G --> I{GitHub Release exists?}
  H --> I
  I -- No --> J[Publish GitHub Release]
  I -- Yes --> K[Leave existing Release unchanged]

Loading

_{Reviews (1): Last reviewed commit: "docs(config): record the release-artifac..." | Re-trigger Greptile}