diff --git a/.github/guid-index.json b/.github/guid-index.json index e6cb450d..9d9137c0 100644 --- a/.github/guid-index.json +++ b/.github/guid-index.json @@ -1003,7 +1003,7 @@ "path": ".github/workflows/reusable-release.yml", "guid": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e", "title": "Reusable Release Coordinator", - "version": "2.16.1", + "version": "2.17.0", "header_path": ".github/workflows/reusable-release.yml", "path_mismatch": false }, diff --git a/.github/workflows/reusable-release.yml b/.github/workflows/reusable-release.yml index 5883b4af..96ae84b2 100644 --- a/.github/workflows/reusable-release.yml +++ b/.github/workflows/reusable-release.yml @@ -1,7 +1,7 @@ # file: .github/workflows/reusable-release.yml -# version: 2.16.1 +# version: 2.17.0 # guid: 7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e -# last-edited: 2026-10-16 +# last-edited: 2026-11-06 name: Reusable Release Coordinator @@ -776,90 +776,6 @@ jobs: ./artifacts/**/* token: ${{ secrets.GITHUB_TOKEN }} - # Assemble CHANGELOG.md from changelog.d/ fragments (scriv) and commit it - # back to the default branch. Opt-in by presence: only runs when the - # calling repo has changelog.d/scriv.ini (see changelog.d/README.md in - # falkcorp/github-common). No-op for every repo without that file. - - name: Collect changelog fragments - if: >- - github.event_name != 'pull_request' && - inputs.changelog-collect != 'false' && - needs.detect-languages.outputs.auto-prerelease != 'true' && - hashFiles('changelog.d/scriv.ini') != '' - env: - VERSION: ${{ steps.version.outputs.version }} - DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} - CHANGELOG_PAT: ${{ secrets.JF_CI_GH_PAT }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - set -euo pipefail - - if [ -z "${VERSION:-}" ]; then - echo "::warning::No version resolved; skipping changelog collect." - exit 0 - fi - - # Defensive: scriv needs a CHANGELOG.md carrying the insert marker. - # Skip cleanly if the repo has scriv.ini but no marker-bearing changelog. - if [ ! -f CHANGELOG.md ] || ! grep -q 'scriv-insert-here' CHANGELOG.md; then - echo "::warning::changelog.d/scriv.ini present but CHANGELOG.md lacks the scriv-insert-here marker; skipping collect." - exit 0 - fi - - # Only real fragments count — README.md, templates/ and scriv.ini don't. - # - # Do NOT write this as `find ... | grep -q .`. `grep -q` exits on the - # first match, closing the pipe; `find` then dies on EPIPE, and under - # `set -o pipefail` the pipeline reports FAILURE even though grep - # succeeded. The leading `!` therefore fires this "no fragments" - # branch precisely when there are MANY fragments — and it exit 0s, so - # the release stays green while collection is silently skipped. - # - # The trigger is a RACE, not a size threshold: `find` loses only if it - # is still writing when `grep` exits. A handful of fragments fit in a - # single write() that lands before grep is scheduled, so nothing goes - # wrong; hundreds mean many writes and grep almost always wins first. - # Note 36 KB is well under the 64 KB pipe buffer — a FULL buffer is - # not what breaks this. audiobook-organizer collected fine at 131 - # fragments, then silently skipped six releases at 675. - # `-print -quit` stops at the first hit and needs no pipeline at all. - if [ -z "$(find changelog.d -maxdepth 1 -name '*.md' ! -name 'README.md' -print -quit)" ]; then - echo "::notice::No changelog fragments to collect for ${VERSION}." - exit 0 - fi - - python3 -m pip install --quiet scriv - - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - - python3 -m scriv collect --version "${VERSION}" - - if git diff --quiet && git diff --cached --quiet; then - echo "::notice::scriv produced no CHANGELOG.md changes." - exit 0 - fi - - git add -A CHANGELOG.md changelog.d - # [skip ci] stops this changelog commit from retriggering release CI. - git commit -m "docs(changelog): collect fragments for ${VERSION} [skip ci]" - - # Prefer the PAT (passes branch protection); fall back to the workflow - # token. Push to an explicit authenticated URL so we don't depend on the - # checkout's persisted credentials. - TOKEN="${CHANGELOG_PAT:-$GITHUB_TOKEN}" - REMOTE="https://x-access-token:${TOKEN}@github.com/${GITHUB_REPOSITORY}.git" - - n=0 - until git push "${REMOTE}" "HEAD:${DEFAULT_BRANCH}" || [ "$n" -ge 4 ]; do - n=$((n + 1)) - echo "Retry $n/4 for changelog push..." - sleep $((2 ** n)) - git pull --rebase "${REMOTE}" "${DEFAULT_BRANCH}" - done - [ "$n" -lt 4 ] || { echo "::error::Failed to push CHANGELOG.md"; exit 1; } - echo "CHANGELOG.md updated for ${VERSION}" - - name: Create or update draft full release if: needs.detect-languages.outputs.auto-prerelease == 'true' && github.event_name != 'pull_request' env: @@ -1241,6 +1157,265 @@ jobs: echo "🎉 Floating tags updated successfully" + # Changelog collection runs in its own job, after the release exists, so a + # failure here can never stop publish-github-packages or update-floating-tags. + # Until 2026-11-06 it was the last step of create-release, ahead of + # check-release: a rejected push failed the job before `release-created` was + # written, and both publish jobs skipped (audiobook-organizer v0.223.0). + # + # Opt-in by presence: only collects when the calling repo has + # changelog.d/scriv.ini (see changelog.d/README.md in falkcorp/github-common). + # + # `!cancelled()`, not `always()`: the upstream build-* jobs are often skipped, + # and a job-level `if:` without a status function gets an implicit + # `success()` that would skip this job too; `!cancelled()` avoids that and + # still honours a cancelled run. + collect-changelog: + name: Collect Changelog Fragments + runs-on: ubuntu-latest + timeout-minutes: 15 + needs: [detect-languages, create-release] + if: >- + !cancelled() && + needs.create-release.outputs.release-created == 'true' && + github.event_name != 'pull_request' && + inputs.changelog-collect != 'false' && + needs.detect-languages.outputs.auto-prerelease != 'true' + steps: + # The released commit (github.sha), so exactly the fragments that shipped + # in this version are collected; fragments merged after it stay pending. + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + + # Every cheap reason to skip, before a token is minted or anything pushed. + - name: Decide whether to collect + id: plan + env: + VERSION: ${{ needs.create-release.outputs.version }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + run: | + set -euo pipefail + collect=false + if [ -z "${VERSION:-}" ]; then + echo "::warning::No version resolved; skipping changelog collect." + # Only the default branch's fragments belong in its CHANGELOG.md. Test + # ancestry, not github.ref_name: a tag-push release has the tag as its + # ref name, and a tag on the default branch must still collect. (Only + # the changelog commit is ever cherry-picked across, so a release cut + # elsewhere could not carry other commits; it simply has nothing to + # collect here.) + elif ! git merge-base --is-ancestor "$GITHUB_SHA" "origin/${DEFAULT_BRANCH}"; then + echo "::warning::${GITHUB_SHA} is not on ${DEFAULT_BRANCH}; skipping changelog collect." + elif [ ! -f changelog.d/scriv.ini ]; then + echo "::notice::No changelog.d/scriv.ini; nothing to collect." + elif [ ! -f CHANGELOG.md ] || ! grep -q 'scriv-insert-here' CHANGELOG.md; then + echo "::warning::changelog.d/scriv.ini present but CHANGELOG.md lacks the scriv-insert-here marker; skipping collect." + # Only real fragments count -- README.md, templates/ and scriv.ini don't. + # Never `find ... | grep -q .`: grep exits on the first match, find dies + # on EPIPE, and pipefail reports failure exactly when there are MANY + # fragments (audiobook-organizer silently skipped six releases at 675). + # `-print -quit` stops at the first hit and needs no pipeline. + elif [ -z "$(find changelog.d -maxdepth 1 -name '*.md' ! -name 'README.md' -print -quit)" ]; then + echo "::notice::No changelog fragments to collect for ${VERSION}." + else + collect=true + fi + echo "collect=${collect}" >> "$GITHUB_OUTPUT" + + # Same guard as build-go: `if:` cannot read secrets.* in a workflow_call + # workflow, so materialise CI_APP_ID through env first. + - name: Check for App credentials + id: check-app + if: steps.plan.outputs.collect == 'true' + env: + CI_APP_ID: ${{ secrets.CI_APP_ID }} + run: | + if [ -n "$CI_APP_ID" ]; then + echo "have-app=true" >> "$GITHUB_OUTPUT" + else + echo "have-app=false" >> "$GITHUB_OUTPUT" + fi + + # Used only if the default branch refuses a direct push (a ruleset or a + # merge queue with no bypass). A pull request opened with GITHUB_TOKEN + # starts no pull_request workflows, so its required checks would never + # report; one opened with an App token (or a user PAT) does. + - name: Mint App token for the changelog pull request + id: app-token + if: steps.plan.outputs.collect == 'true' && steps.check-app.outputs.have-app == 'true' + uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0 + with: + app-id: ${{ secrets.CI_APP_ID }} + private-key: ${{ secrets.CI_APP_PRIVATE_KEY }} + + - name: Collect changelog fragments + if: steps.plan.outputs.collect == 'true' + env: + VERSION: ${{ needs.create-release.outputs.version }} + DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} + CHANGELOG_PAT: ${{ secrets.JF_CI_GH_PAT }} + APP_TOKEN: ${{ steps.app-token.outputs.token }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + set -euo pipefail + BRANCH="changelog/collect-${VERSION}" + + # An earlier release's changelog PR that has not merged yet still + # leaves its fragments in this checkout; collecting now would file + # them under this version too. Refuse instead (needs a token that can + # read pull requests; GITHUB_TOKEN usually cannot, so skip if absent). + # This version's own branch is excluded: a re-run reuses its PR. + LIST_TOKEN="${APP_TOKEN:-${CHANGELOG_PAT:-}}" + if [ -n "$LIST_TOKEN" ]; then + if ! pending="$(GH_TOKEN="$LIST_TOKEN" gh pr list --repo "$GITHUB_REPOSITORY" --state open --limit 1000 \ + --json headRefName,isCrossRepository \ + --jq "[.[] | select(.isCrossRepository == false and (.headRefName | startswith(\"changelog/collect-\")) and .headRefName != \"${BRANCH}\") | .headRefName] | join(\" \")")"; then + # Repos that push directly never have such a PR; do not fail + # their release because this token cannot read pull requests. + echo "::warning::Could not list open pull requests; not checking for an earlier unmerged changelog PR." + pending="" + fi + if [ -n "$pending" ]; then + echo "::error::Changelog pull request(s) still open: ${pending}. Merge or close them, then re-run this job; collecting now would file their fragments under ${VERSION} as well." + exit 1 + fi + fi + + python3 -m pip install --quiet scriv + + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + python3 -m scriv collect --version "${VERSION}" + + if git diff --quiet && git diff --cached --quiet; then + echo "::notice::scriv produced no CHANGELOG.md changes." + exit 0 + fi + + git add -A CHANGELOG.md changelog.d + # [skip ci] stops a directly pushed changelog commit from retriggering + # release CI. The pull-request path below removes it. + git commit -m "docs(changelog): collect fragments for ${VERSION} [skip ci]" + COMMIT="$(git rev-parse HEAD)" + + # Only the changelog may travel. Anything else means scriv or the + # checkout did something unexpected; never push it. + other="$(git diff --name-only "${COMMIT}^" "${COMMIT}" | grep -vE '^(CHANGELOG\.md|changelog\.d/)' || true)" + if [ -n "$other" ]; then + echo "::error::The changelog commit touches files outside CHANGELOG.md and changelog.d/: ${other}" + exit 1 + fi + + # Put the one changelog commit on a fresh copy of the default branch's + # tip. Never push the checkout's own history. + land_on_tip() { + git fetch --quiet "https://x-access-token:${1}@github.com/${GITHUB_REPOSITORY}.git" "${DEFAULT_BRANCH}" + git checkout --quiet --detach FETCH_HEAD + git cherry-pick "${COMMIT}" + } + + # 1. Direct push, as before, for repositories that allow it. Prefer the + # PAT, fall back to the workflow token. + PUSH_TOKEN="${CHANGELOG_PAT:-$GITHUB_TOKEN}" + ERR="$(mktemp)" + n=0 + while :; do + land_on_tip "$PUSH_TOKEN" + if git push "https://x-access-token:${PUSH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "HEAD:${DEFAULT_BRANCH}" 2>"$ERR"; then + cat "$ERR" + echo "CHANGELOG.md updated for ${VERSION}" + exit 0 + fi + cat "$ERR" >&2 + # A protection or ruleset refusal is permanent; retrying cannot help. + if grep -qiE 'GH013|GH006|protected branch|Repository rule violations' "$ERR"; then + break + fi + n=$((n + 1)) + if [ "$n" -ge 4 ]; then + echo "::error::Failed to push CHANGELOG.md after $n retries" + exit 1 + fi + echo "Retry $n/4 for changelog push..." + sleep $((2 ** n)) + done + + # 2. The default branch refuses direct pushes: land the same commit + # through a pull request, set to merge as soon as its required checks + # pass (a merge queue then takes it). No [skip ci]: the PR's checks + # must run. "[skip changelog]" in the title exempts it from + # fragment-required checks. Only the App token or the PAT can open + # it: a GITHUB_TOKEN-opened PR starts no checks and could not merge. + echo "::notice::${DEFAULT_BRANCH} refuses direct pushes; opening a pull request instead." + TITLE="docs(changelog): collect fragments for ${VERSION} [skip changelog]" + BODY="Folds the changelog.d fragments released in ${VERSION} into CHANGELOG.md. Opened by the release workflow because ${DEFAULT_BRANCH} refuses direct pushes." + + opened="" + PR="" + HEAD_SHA="" + # The same-repository PR for BRANCH, by number. Never resolve a PR by + # branch name alone: a fork can open one with the same head name. + own_pr() { + gh pr list --repo "$GITHUB_REPOSITORY" --head "$BRANCH" --state open \ + --json number,isCrossRepository \ + --jq '[.[] | select(.isCrossRepository == false)][0].number // empty' || true + } + for kind in app pat; do + if [ "$kind" = app ]; then TOKEN="${APP_TOKEN:-}"; else TOKEN="${CHANGELOG_PAT:-}"; fi + if [ -z "$TOKEN" ]; then + echo "::notice::No ${kind} token configured." + continue + fi + land_on_tip "$TOKEN" + git commit --quiet --amend -m "docs(changelog): collect fragments for ${VERSION}" + HEAD_SHA="$(git rev-parse HEAD)" + if ! git push --force "https://x-access-token:${TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "HEAD:refs/heads/${BRANCH}"; then + echo "::warning::Could not push ${BRANCH} with the ${kind} token; trying the next one." + continue + fi + export GH_TOKEN="$TOKEN" + PR="$(own_pr)" + if [ -z "$PR" ]; then + if ! gh pr create --repo "$GITHUB_REPOSITORY" --base "$DEFAULT_BRANCH" --head "$BRANCH" \ + --title "$TITLE" --body "$BODY"; then + echo "::warning::Could not open the pull request with the ${kind} token; trying the next one." + continue + fi + PR="$(own_pr)" + fi + if [ -z "$PR" ]; then + echo "::warning::Opened ${BRANCH} but cannot find its pull request with the ${kind} token; trying the next one." + continue + fi + opened="$kind" + break + done + if [ -z "$opened" ]; then + echo "::error::Could not open the changelog pull request for ${VERSION}: set CI_APP_ID/CI_APP_PRIVATE_KEY (App with contents and pull-requests write) or JF_CI_GH_PAT." + exit 1 + fi + if [ "$opened" = pat ] && [ -n "${APP_TOKEN:-}" ]; then + echo "::warning::The App token could not open the pull request (does the App have pull-requests write?); it was opened with JF_CI_GH_PAT." + fi + + # Merge by number, pinned to the commit pushed above. Auto-merge needs + # allow_auto_merge and something still pending; if it cannot be + # enabled, merge now (on a merge-queue branch that enqueues). Never + # --admin: required checks, reviews and the queue still apply, and the + # commit was checked above to touch only the changelog. + if gh pr merge "$PR" --repo "$GITHUB_REPOSITORY" --rebase --auto --match-head-commit "$HEAD_SHA"; then + echo "::notice::Changelog pull request #${PR} for ${VERSION} will merge once its required checks pass." + elif gh pr merge "$PR" --repo "$GITHUB_REPOSITORY" --rebase --match-head-commit "$HEAD_SHA"; then + echo "::notice::Changelog pull request #${PR} for ${VERSION} merged (or entered the merge queue)." + else + echo "::error::Opened changelog pull request #${PR} for ${VERSION} but could neither enable auto-merge nor merge it; merge it by hand." + exit 1 + fi + # Final status check build-status: name: Release Status Summary @@ -1256,6 +1431,7 @@ jobs: create-release, publish-github-packages, update-floating-tags, + collect-changelog, ] if: always() outputs: diff --git a/changelog.d/20261106_changelog_collect_job_pr_fallback.md b/changelog.d/20261106_changelog_collect_job_pr_fallback.md new file mode 100644 index 00000000..6e2c7beb --- /dev/null +++ b/changelog.d/20261106_changelog_collect_job_pr_fallback.md @@ -0,0 +1,32 @@ +### Fixed + +#### `reusable-release.yml`: changelog collection no longer blocks publishing, and lands through a PR when the default branch refuses pushes + +Changelog collection was the last step of `create-release`, ahead of the step +that writes `release-created`. When its push to the default branch was refused +(a ruleset or merge queue with no bypass: `GH013`), the job failed before that +output existed, so `publish-github-packages` was skipped for a release that had +been created with all its assets. + +- Collection is now its own job, `collect-changelog`, after `create-release`. + Its failure turns the run red but cannot skip publishing. `build-status` waits + for it. +- A first step decides whether there is anything to collect (the released + commit is on the default branch, which a tag-push release also passes, `changelog.d/scriv.ini` and the CHANGELOG marker exist, + fragments are pending) before any token is minted. +- It collects at the released commit and checks the commit touches only + `CHANGELOG.md` and `changelog.d/`, then cherry-picks that one commit onto a + fresh fetch of the default branch. The old step pushed (or rebased) the + checkout's own history, so a release cut from another branch could carry + that branch's commits to the default branch. +- It still tries the direct push first. On a protection or ruleset refusal it + opens a pull request from `changelog/collect-` with the `CI_APP_ID` + App token, or `JF_CI_GH_PAT` if the App cannot, and enables rebase auto-merge + (falling back to a plain rebase merge, which enqueues on a merge-queue + branch). A PR opened with `GITHUB_TOKEN` starts no checks, so that token is + not used for it. The PR commit drops `[skip ci]`; its title carries + `[skip changelog]`. +- It refuses to collect while an earlier version's `changelog/collect-*` PR is + still open, so fragments are never filed under two versions. A re-run of the + same version reuses its own PR, and a token that cannot list pull requests + only warns, so repos that push directly are unaffected.