backport: post a backport checklist automatically on pull requests targeting main

[mrodm]

Summary

Add a package detection utility script and a two-workflow pair that automatically posts a backport checklist comment on any PR targeting main that touches packages with active backport branches. The checklist lets authors opt in to backporting on a per-branch basis — no label required. Nothing is backported until a box is checked.

Background

Currently there is no mechanism to surface which backport branches are relevant for a given PR or to track which backports have been requested. Backports are easy to forget, especially as the number of maintained branches grows.

The checklist is implemented as a two-workflow pair to safely support PRs from forks: the pull_request workflow runs in the restricted fork context (read-only, no secrets), while the workflow_run workflow runs in the base repository context (with write permissions). Fork code is never checked out or executed with write permissions.

Deliverables

dev/scripts/backport_detect_packages.sh

Maps a list of changed file paths to the package names they belong to.

Detection logic: for each changed file, find the shallowest ancestor directory under packages/ that contains a manifest.yml. Read the name field from that manifest.yml — do not use the directory name as the package name. Handles the current flat structure and any future nested packages/<tech>/<name>/ structure.

Flags: --json (emits a JSON array instead of newline-separated output)

backport-packages-detect.yml

Runs on pull_request (opened/synchronize) targeting main. Read-only — no write permissions, no secrets.

• Permissions: none (default read-only)

1. Gets changed files from the PR event payload
2. Calls backport_detect_packages.sh --json
3. Uploads artifact: { "pr_number": 1234, "sha": "abc123", "packages": ["aws", "kubernetes"] }

post-backport-checklist.yml

Runs on workflow_run completion of backport-packages-detect. Runs in the base repository context with write permissions. Fork code is never executed here.

• Permissions: pull-requests: write

1. Downloads the artifact from the triggering workflow run
2. For each package, looks up active backport branches via backport_check_active.sh
3. If no active branches found across all packages: exits silently
4. Posts or updates the checklist comment:

<!-- backport-checklist -->
## Backport checklist

Check the branches to backport this change to. PRs will be created automatically
on merge, or when you update this checklist after merge.

**aws**
- [ ] `backport-aws-6.14` (maintained until 2027-01-15)
- [ ] `backport-aws-3.17`

---

> [!TIP]
> If a branch above is no longer required, set `archived: true` in its entry in
> `.backports.yml` to stop it appearing in future checklists.
> If the branch has a known end-of-life date, prefer `maintained_until: "YYYY-MM-DD"` —
> it will be excluded automatically once that date passes.

On update (synchronize event): adds newly affected packages while preserving all existing checkbox states (checked or unchecked).

Considerations

• Folder name vs. package name: the directory name under packages/ is not guaranteed to match the name field in manifest.yml. The script must read the name field from manifest.yml to get the authoritative package name — this is the value stored in .backports.yml and used as the lookup key across all backport tooling.

• No pull_request_target: the two-workflow pattern (pull_request + workflow_run) is the intentional design to avoid the security risks of pull_request_target. Do not replace it with pull_request_target even if it seems simpler.

Acceptance criteria

• Checklist appears automatically on PRs that touch packages with active backport branches
• No checklist appears on PRs touching only non-package files
• Checklist updates correctly when new commits touch additional packages, preserving checked boxes
• Works correctly for PRs from forks
• No checklist is posted if none of the touched packages have active backport branches
• Package name is read from manifest.yml, not inferred from the directory name

[infra-vault-gh-plugin-prod]

Pinging @elastic/ecosystem (Team:Ecosystem)

[github-actions]

tl;dr: #19213 is ready to implement now and should land before #19214; the repo already has a proven fork-safe pull_request → workflow_run comment pattern to reuse, and the requested script/workflows for this issue are not present yet.

Recommendation

Implement #19213 as the next step in the backport epic, using the same two-workflow artifact handoff pattern used by existing docs/vale workflows, and treat the checklist comment format (<!-- backport-checklist --> + per-branch checkboxes) as a contract that #19214 will consume.

Findings

• Current backport flow is Buildkite/manual, not PR-checklist automation:
  • .buildkite/pipeline.backport.yml:13-21,52-54
  • .buildkite/scripts/backport_branch.sh:90-106,270-276
  • docs/extend/developer-workflow-support-old-package.md:10-16,81-84,117-121
• Existing helper script already resolves package identity from manifest.yml name field (good precedent for detector behavior):
  • dev/scripts/get_release_commit.sh:40-49
• Fork-safe two-workflow pattern already exists and matches this issue’s security model:
  • Detector (read-only PR): validate-package-docs.yml:4-12
  • Artifact upload from detector: validate-package-docs.yml:89-97
  • Reporter (workflow_run) with write perms: notify-package-docs-failure.yml:4-15
  • Reporter integrity check before comment write: notify-package-docs-failure.yml:40-47
  • Similar pattern documented for vale: vale-lint.yml:12-22, vale-report.yml:16-23,30-32
• No implementation of #19213 deliverables exists in-tree yet:
  • no .github/workflows/backport-packages-detect.yml
  • no .github/workflows/post-backport-checklist.yml
  • no dev/scripts/backport_detect_packages.sh
• Sequencing: #19214 explicitly depends on checklist output from this issue (“With the checklist in place...”), so #19213 should be done first.

Verification

I ran quick workspace checks to confirm current state and avoid duplicate recommendations:

$ ls .github/workflows | grep -i backport
# (no output)

$ test -f dev/scripts/backport_detect_packages.sh && echo yes || echo no
no

$ test -f .backports.yml && echo yes || echo no
no

$ ./dev/scripts/get_release_commit.sh -p aws -v 6.18.0 | head -n1
9004e054

Detailed Action Plan

1. Add dev/scripts/backport_detect_packages.sh to map changed file paths to package names via the shallowest packages/.../manifest.yml, reading the authoritative name field (not directory name).
2. Support --json output (JSON array) and default newline output for reuse.
3. Add .github/workflows/backport-packages-detect.yml:
   • trigger: pull_request (opened, synchronize, optionally reopened) targeting main
   • permissions: read-only (contents: read)
   • read changed files, run detector, upload artifact with {pr_number, sha, packages}.
4. Add .github/workflows/post-backport-checklist.yml:
   • trigger: workflow_run of backport-packages-detect
   • job gate: run only when source event is pull_request and not cancelled
   • permissions: pull-requests: write + actions: read.
5. In reporter workflow, resolve active backport branches per package (using backport_check_active.sh as specified by issue scope) and exit silently if none are active.
6. Implement comment upsert keyed by marker <!-- backport-checklist --> so there is one canonical checklist comment per PR.
7. On synchronize updates, merge newly detected packages/branches into existing comment while preserving prior checkbox states.
8. Keep pull_request_target out of this implementation; preserve fork-safety by never checking out/executing PR code in the write-capable workflow.

Related Items

Type	Link	Relevance
Issue	#19016	Parent epic for backport automation
Issue	#19213	This checklist-comment automation scope
Issue	#19214	Downstream consumer of checklist output (should follow #19213)
PR	#19104	Added dev/scripts/get_release_commit.sh and docs improvements; useful precedent
File	.buildkite/pipeline.backport.yml	Current Buildkite backport entrypoint
File	.buildkite/scripts/backport_branch.sh	Existing package-name-from-manifest behavior
File	.github/workflows/validate-package-docs.yml	Existing detector + artifact pattern
File	.github/workflows/notify-package-docs-failure.yml	Existing workflow_run commenter + SHA/PR validation pattern
File	.github/workflows/vale-lint.yml + .github/workflows/vale-report.yml	Existing fork-safe two-workflow split

Note

🔒 Integrity filter blocked 12 items

The following items were blocked because they don't meet the GitHub integrity level.

• #18828 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #18141 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #14064 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #11289 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #5614 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #13847 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #13848 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #13849 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #13850 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #18995 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #16732 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #19171 pull_request_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

---

What is this? | From workflow: Issue Triage

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[mrodm]

Updating the description to include the full format of the checklist comment the automation posts — specifically adding a [!TIP] callout at the bottom pointing authors to .backports.yml if they need to disable a branch from future checklists.

<!-- backport-checklist -->
## Backport checklist

Check the branches to backport this change to. PRs will be created automatically
on merge, or when you update this checklist after merge.

**aws**
- [ ] `backport-aws-6.14` (maintained until 2027-01-15)
- [ ] `backport-aws-3.17`

---

> [!TIP]
> If a branch above is no longer required, set `archived: true` in its entry in
> `.backports.yml` to stop it appearing in future checklists.
> If the branch has a known end-of-life date, prefer `maintained_until: "YYYY-MM-DD"` —
> it will be excluded automatically once that date passes.

[mrodm]

I think this process could also check the existence of the automation label. If that label is present, the whole process could be skipped.

In this PR , it is being proposed to change the automation label to backport:sync-changelog #19930. Thereby, this process uses a specific label that is not used by other automation processes.