backport: sync changelog entries from backport branches to main automatically #19215

Summary

Add sync-backport-changelog.yml, a GitHub Actions workflow that automatically opens a PR against main to insert new changelog entries whenever any commit is pushed to a backport-<package>-* branch. This keeps main's package changelogs current without a manual step, for both automated and manually created backport PRs.

Background

When a fix lands on a backport branch, the changelog.yml entry for that version only exists on that branch. Without this workflow, the entry must be manually copied to main's changelog — a step that is easy to forget and causes the integrations site changelog to be incomplete or out of date.

This workflow is fully independent of the rest of the backport tooling: it requires no .backports.yml check, no active-branch evaluation, and no other script. If work was pushed to a backport branch, it should be synced regardless of the branch's inventory status.

Deliverables

sync-backport-changelog.yml

Trigger: push to branches matching backport-*

Permissions: contents: write, pull-requests: write

Flow:

1. Zero-SHA guard: exit silently on branch-creation pushes (nothing to diff)
2. Parse package name from branch name (backport-<package>-<major.minor>) — exit silently if no match
3. Diff changelog.yml: git diff <before>..<after> -- packages/<package>/changelog.yml — exit silently if no changelog change
4. Extract the new version entry from the diff (only + lines forming a complete version block, verified as valid YAML)
5. Idempotency check: verify the version does not already exist in main's changelog.yml — exit silently if it does
6. Insert the entry at the correct semver-descending position in main's changelog.yml
7. Open PR: working branch changelog-sync/<package>-<version>; deduplicate via gh pr list --head <working-branch> --state all; label automation to prevent auto-backport.yml re-triggering on merge

No active-branch check — if work was pushed to a backport branch, the changelog entry should be synced regardless of the branch's inventory status.

Considerations

• Nested package directories: step 3 diffs packages/<package>/changelog.yml, but the package may live under packages/<technology>/<package>. The workflow must resolve the package name (parsed from the branch name) to its actual filesystem path. Investigate whether mage listPackages or an equivalent helper provides a name → path mapping, or whether a find-based lookup is needed.

Acceptance criteria

• Merging any PR onto a backport branch opens a PR against main inserting the new version entry at the correct semver-descending position
• Re-running the workflow (or a second push) does not open a duplicate PR
• Workflow is a no-op on branch-creation pushes (zero-SHA guard)
• Synced PRs are labelled automation and do not re-trigger auto-backport.yml on merge
• Works for both automated (auto-backport.yml) and manually created backport PRs
• Works correctly for packages under nested directories (packages/<technology>/<package>)