Resolve CHANGELOG-only conflicts in open PRs automatically

[NinjaLikesCheez]

Stacked on #143. Review and merge that first; this PR's base then moves to main.

Why

When one PR merges, every other open PR that added a CHANGELOG entry conflicts in CHANGELOG.md, usually nowhere else, and the fix is nearly always "keep both". After a release, every open PR conflicts, because [Unreleased] was emptied.

What it does

scripts/changelog-merge.ts: a structured three-way merge of CHANGELOG.md, not git's line union (which can duplicate ### Fixed, or interleave entries that span several lines). Given base / branch (PR) / main:

• It starts from main's file and applies the branch's [Unreleased] changes. Entries the branch added go at the end of their section, and a missing section is created in Keep a Changelog order, never twice. An entry both sides added is kept once. An entry the branch reworded or removed is changed only if main still has it untouched.
• A release in between is handled. Main's [Unreleased] is empty or new, and the branch's added entries land there, not in the version that was cut.
• It refuses, leaving the conflict to a person, when:
  • both sides changed the same entry
  • the branch edited an entry that has since been released
  • either side has a section twice, an unknown ### heading, or prose that isn't a list entry
  • both sides changed the intro, the released versions or the link footer
  • a side still has conflict markers

.github/workflows/changelog-merge.yml: runs on push to main touching CHANGELOG.md. It also runs on workflow_run after Release, because the bump commit is pushed with GITHUB_TOKEN and so doesn't fire push. Plus workflow_dispatch. For each open, same-repo PR that edits CHANGELOG.md, it does git merge --no-commit origin/main in a worktree:

• no conflict → nothing to do
• other files conflict too → left alone
• only CHANGELOG.md → resolve, commit, push (never forced), and comment
• refused → abort, and comment with the reason

There's one comment per PR, edited in place. The job summary lists each PR's outcome.

Local: just changelog-merge in a stopped merge or rebase (a rebase is detected, so the sides swap correctly). just changelog-merge-driver registers it as a git merge driver for this clone only, via .git/info/attributes, so nothing is committed.

Edge cases and how they're handled

Case	Handling
A release went out between the PR's base and main	Branch's new entries go into the new [Unreleased]; editing a released entry → refuse
Both sides add to the same section	Main's entries first, then the branch's; one heading
Branch adds a section main doesn't have	Inserted in Added/Changed/Deprecated/Removed/Fixed/Security order
Same entry on both sides (cherry-pick, or the PR already merged main)	Kept once
Both sides reworded the same entry	Refuse + comment
Duplicate ### Fixed already on a side (a bad earlier merge)	Refuse; a person fixes it
Multi-line or multi-paragraph bullets	Treated as one entry (bullet + indented lines)
Conflicts outside CHANGELOG.md	Untouched; GitHub's own conflict banner covers it
Fork PRs	Skipped (can't push there, and they're untrusted)
Author pushes while the job runs	Non-forced push is rejected; the next main push retries
Untrusted PR content	Only main's resolver runs. PR branches are only git merged (no install, build or hooks; .gitattributes can't name a driver without our config)
Pushes with GITHUB_TOKEN don't trigger CI	Uses a GitHub App token when CHANGELOG_BOT_CLIENT_ID / CHANGELOG_BOT_PRIVATE_KEY are set; otherwise falls back and the comment says CI needs a re-push or close/reopen
Main's merge brings in .github/workflows/ changes	GITHUB_TOKEN can't push that ("workflows" permission); the App has it. Without the App the push is refused and logged
Unsigned bot commits	Fine today (the ruleset is disabled). If signed commits are ever required, the App would need to commit through the API

Setup needed (maintainer)

Create a GitHub App with Contents, Pull requests and Workflows: read and write, and install it on pixelbar/pixel. Then set the repo variable CHANGELOG_BOT_CLIENT_ID and the secret CHANGELOG_BOT_PRIVATE_KEY. The runbook's "Changelog conflicts" section covers it. It works without the App, with the caveats above.

Verified

• 23 resolver tests. They cover each refusal, release-in-between, multi-line entries, round-tripping the real file's head, versions and links byte for byte, and --git in a real merge, a real rebase, and as a merge driver (including leaving conflict markers on refusal). just check and just docs-build pass, and actionlint is clean.
• Dry run against current open PRs (local, nothing pushed): Never mark another run's online post offline when shutting down #130, Bound the Mastodon response body read and cancel oversized bodies #129 and Stop CD losing images and gate Release on just check #137 resolved; Centralise laptop tooling around one env definition (#116) #121 had no conflict; Skip the Sentry heartbeat when PIXEL_ENV=local #132 and Tailscale sidecar: userspace SOCKS5 and localhost HA proxy (#74) #76 have other conflicts too, so they'd be left alone.
• Used it for real: Skip CI jobs whose exact inputs already passed #143 conflicted with main in CHANGELOG.md only. I resolved that with this resolver (6 Fixed entries from main + this stack's Changed entry, one heading each) and pushed.
• Not yet run on GitHub. The workflow first runs once this is on main.

🤖 Generated with Claude Code