release.yml

name: Release

on:
  push:
    branches:
      - develop
  workflow_dispatch:
    inputs:
      version:
        description: Unshipped product version to refresh from develop
        required: true
        type: string
      replace_candidate_sha:
        description: Exact current candidate SHA to replace (leave empty for a fast-forward refresh)
        required: false
        type: string
      expected_develop_sha:
        description: Exact develop SHA for a replacement candidate
        required: false
        type: string

# Every push re-checks the live develop version. Tagged versions are no-ops;
# an untagged version means a maintainer merged a release PR and is ready for
# the frozen promotion gate. Maintainers can explicitly refresh an unshipped
# candidate after amending its release notes on develop.
concurrency:
  group: release-develop
  cancel-in-progress: false

permissions:
  contents: write
  pull-requests: write

jobs:
  promote:
    name: Open or refresh Promote PR
    runs-on: blacksmith-4vcpu-ubuntu-2404
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          token: ${{ secrets.RELEASE_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          fetch-depth: 0
          ref: develop

      - name: Cut or refresh release candidate and open promote PR
        env:
          EVENT_NAME: ${{ github.event_name }}
          GH_TOKEN: ${{ secrets.RELEASE_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          RELEASE_BOT_TOKEN: ${{ secrets.RELEASE_BOT_TOKEN }}
          REQUESTED_VERSION: ${{ inputs.version }}
          REPLACE_CANDIDATE_SHA: ${{ inputs.replace_candidate_sha }}
          EXPECTED_DEVELOP_SHA: ${{ inputs.expected_develop_sha }}
        shell: bash
        run: |
          set -euo pipefail

          current_version="$(node -p "require('./package.json').version")"
          version="$current_version"
          replace_candidate_sha="${REPLACE_CANDIDATE_SHA:-}"
          expected_develop_sha="${EXPECTED_DEVELOP_SHA:-}"
          replace_candidate=false
          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
            version="${REQUESTED_VERSION#v}"
            if [ "$version" != "$current_version" ]; then
              echo "Cannot refresh ${version}: develop is currently version ${current_version}."
              exit 1
            fi
            if [ -n "$replace_candidate_sha" ] || [ -n "$expected_develop_sha" ]; then
              if ! [[ "$replace_candidate_sha" =~ ^[0-9a-f]{40}$ ]] || ! [[ "$expected_develop_sha" =~ ^[0-9a-f]{40}$ ]]; then
                echo "Candidate replacement requires full lowercase replace_candidate_sha and expected_develop_sha values."
                exit 1
              fi
              if [ "$(git rev-parse HEAD)" != "$expected_develop_sha" ]; then
                echo "Cannot replace ${version}: develop moved from expected ${expected_develop_sha} to $(git rev-parse HEAD)."
                exit 1
              fi
              if [ -z "$RELEASE_BOT_TOKEN" ]; then
                echo "Cannot replace ${version}: RELEASE_BOT_TOKEN is required to trigger fresh candidate checks."
                exit 1
              fi
              replace_candidate=true
            fi
          fi
          : "${version:?missing package.json version}"
          tag="v${version}"

          if git rev-parse "$tag" >/dev/null 2>&1 || git ls-remote --tags origin "refs/tags/$tag" | grep -q .; then
            echo "Tag $tag already exists; nothing to promote."
            exit 0
          fi

          git fetch origin "refs/heads/main:refs/remotes/origin/main" --quiet

          if ! git show-ref --verify --quiet refs/remotes/origin/main; then
            echo "origin/main is missing; create main before promoting."
            exit 1
          fi

          bump_sha="$(node scripts/release/find-version-commit.mjs "$version" HEAD)"
          release_branch="release/${tag}"
          existing=""

          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
            if ! git ls-remote --exit-code --heads origin "$release_branch" >/dev/null 2>&1; then
              echo "Cannot refresh missing release branch ${release_branch}."
              exit 1
            fi

            git fetch origin "refs/heads/${release_branch}:refs/remotes/origin/${release_branch}" --quiet
            candidate_sha="$(git rev-parse "origin/${release_branch}")"
            if git merge-base --is-ancestor "$candidate_sha" origin/main; then
              echo "Cannot refresh ${tag}: main already contains candidate ${candidate_sha}."
              exit 1
            fi
            if [ "$replace_candidate" = true ]; then
              if [ "$candidate_sha" != "$replace_candidate_sha" ]; then
                echo "Cannot replace ${tag}: expected candidate ${replace_candidate_sha}, found ${candidate_sha}."
                exit 1
              fi
              if [ "$candidate_sha" = "$expected_develop_sha" ]; then
                echo "Cannot replace ${tag}: candidate already matches expected develop."
                exit 1
              fi
              if git merge-base --is-ancestor "$expected_develop_sha" "$candidate_sha"; then
                echo "Cannot replace ${tag}: expected develop ${expected_develop_sha} would regress candidate ${candidate_sha}."
                exit 1
              fi
            elif ! git merge-base --is-ancestor "$candidate_sha" HEAD; then
              echo "Cannot refresh ${tag}: ${release_branch} has diverged from develop."
              exit 1
            fi

            existing="$(gh pr list --base main --head "$release_branch" --state open --json url --jq '.[0].url // empty')"
            if [ -z "$existing" ]; then
              echo "Cannot refresh ${tag}: no open Promote PR targets main."
              exit 1
            fi

            pending_changesets="$(git ls-files '.changeset/*.md' | grep -iv '/README.md$' || true)"
            if [ -n "$pending_changesets" ]; then
              echo "Cannot refresh ${tag} with pending changesets. Amend the current release notes first:"
              echo "$pending_changesets"
              exit 1
            fi

            # Minimize the merge race by repeating the shipped-state and PR
            # checks immediately before moving the candidate branch.
            git fetch origin "refs/heads/main:refs/remotes/origin/main" --tags --quiet
            if git rev-parse "$tag" >/dev/null 2>&1 || git merge-base --is-ancestor "$candidate_sha" origin/main; then
              echo "Cannot refresh ${tag}: the candidate reached main while this refresh was running."
              exit 1
            fi
            existing="$(gh pr list --base main --head "$release_branch" --state open --json url --jq '.[0].url // empty')"
            if [ -z "$existing" ]; then
              echo "Cannot refresh ${tag}: the Promote PR closed while this refresh was running."
              exit 1
            fi

            release_sha="$(git rev-parse HEAD)"
            shipping_guard_sha="$candidate_sha"
            if [ "$replace_candidate" = true ]; then
              git push --force-with-lease="refs/heads/${release_branch}:${candidate_sha}" origin "${release_sha}:refs/heads/${release_branch}"
              candidate_status="Candidate replaced from \`${candidate_sha}\` with \`${release_sha}\` from \`develop\` by [this authorized workflow run](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}). Prior candidate checks, reviews, and reconciliation provenance no longer apply."
              echo "Replaced ${release_branch} at ${candidate_sha} with ${release_sha}"
            else
              git push origin "${release_sha}:refs/heads/${release_branch}"
              candidate_status="Candidate refreshed to \`${release_sha}\` from \`develop\`."
              echo "Refreshed ${release_branch} to ${release_sha}"
            fi
          else
            # Freeze the release at the commit that introduced this version (the
            # release PR merge), not at the moving develop tip. Later commits are
            # included only through an explicit guarded refresh.
            if git merge-base --is-ancestor "$bump_sha" origin/main; then
              echo "main already contains ${bump_sha}; nothing to promote."
              exit 0
            fi

            release_sha="$bump_sha"
            shipping_guard_sha="$release_sha"
            candidate_status="Frozen at \`${release_sha}\` — the commit where \`${version}\` was versioned. Commits merged to \`develop\` afterward require an explicit candidate refresh or ship in the next release."
            if git ls-remote --exit-code --heads origin "$release_branch" >/dev/null 2>&1; then
              remote_release_sha="$(git ls-remote --exit-code --heads origin "refs/heads/${release_branch}" | cut -f1)"
              if [ "$remote_release_sha" != "$release_sha" ]; then
                echo "Release branch ${release_branch} points to ${remote_release_sha}, expected ${release_sha}; refusing to write Promote PR metadata for a different candidate."
                exit 1
              fi
              echo "Release branch ${release_branch} already exists at ${release_sha}; leaving it frozen."
            else
              git push origin "${release_sha}:refs/heads/${release_branch}"
              echo "Cut ${release_branch} at ${release_sha}"
            fi
          fi

          remote_release_sha="$(git ls-remote --exit-code --heads origin "refs/heads/${release_branch}" | cut -f1)"
          if [ "$remote_release_sha" != "$release_sha" ]; then
            echo "Release branch ${release_branch} moved to ${remote_release_sha}, expected ${release_sha}; refusing to update Promote PR metadata."
            exit 1
          fi

          git fetch origin "refs/heads/main:refs/remotes/origin/main" --tags --quiet
          if git rev-parse "$tag" >/dev/null 2>&1 || git merge-base --is-ancestor "$shipping_guard_sha" origin/main; then
            echo "Cannot update Promote PR metadata for ${tag}: the candidate reached main while the branch was being prepared."
            exit 1
          fi
          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
            existing="$(gh pr list --base main --head "$release_branch" --state open --json url --jq '.[0].url // empty')"
            if [ -z "$existing" ]; then
              echo "Cannot refresh ${tag}: the Promote PR closed while the branch was being updated."
              exit 1
            fi
          fi

          notes="$(node scripts/release/extract-changelog-section.mjs "$version" || true)"
          body_file="$(mktemp)"
          {
            echo "## Promote ${tag}"
            echo
            echo "$candidate_status"
            echo
            echo "- Merge this PR with a **merge commit** (do not squash or rebase)."
            echo "- If multiple promote PRs are open, merge them in version order (oldest first)."
            echo "- Monitor CI and reviews on this PR's current head, not only the release-preparation PR. Unresolved findings and missing required approvals remain blockers even with green CI."
            echo "- After a refresh or CI reconciliation, re-check the new head; monitoring never authorizes merging or publication."
            echo "- Merging publishes a GitHub Release for \`${tag}\` and triggers the existing GHCR \`v*\` image publish (\`latest\` channel)."
            echo "- The \`${release_branch}\` branch can be deleted after this PR merges."
            echo
            echo "### Changelog"
            echo
            if [ -n "$notes" ]; then
              echo "$notes"
            else
              echo "_No CHANGELOG section found for ${version}; see commits on develop._"
            fi
          } > "$body_file"

          if [ -z "$existing" ]; then
            existing="$(gh pr list --base main --head "$release_branch" --state open --json url --jq '.[0].url // empty')"
          fi
          if [ -n "$existing" ]; then
            echo "Promote PR already open: $existing"
            gh pr edit "$existing" --title "Promote ${tag} to production" --body-file "$body_file"
            rm -f "$body_file"
            exit 0
          fi

          gh pr create \
            --base main \
            --head "$release_branch" \
            --title "Promote ${tag} to production" \
            --body-file "$body_file"
          rm -f "$body_file"