Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/guid-index.json
Original file line number Diff line number Diff line change
Expand Up @@ -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
},
Expand Down
348 changes: 262 additions & 86 deletions .github/workflows/reusable-release.yml
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -1256,6 +1431,7 @@ jobs:
create-release,
publish-github-packages,
update-floating-tags,
collect-changelog,
]
if: always()
outputs:
Expand Down
Loading
Loading