name: Automatic Backport on: pull_request_target: types: [closed, labeled] # fires when PR is closed (merged) or labeled # Two mechanisms here, answering two different failures. # # A run joins its concurrency group before any job-level `if` is evaluated, so # `prepare`'s guard below cannot stop a label event from disturbing the run # already backporting this PR; it only decides what the label run does after the # damage. Labels set with the default GITHUB_TOKEN start no run, but labels set # by third-party GitHub Apps do, and they arrive in bursts. Under a plain # `cancel-in-progress: true` each one cancelled the backport the merge had just # started, and nothing reports that beyond a cancelled run sitting next to a # green one. # # The delivery survived anyway, because the old guard admitted a run on the PR's # cumulative labels: the last label of a burst requalified and redid the work. # `prepare`'s narrowing below removes that accidental safety net, so the two # changes land together — narrowing alone would turn a noisy delivery into an # absent one. # # So the group key moves a label event that is NOT a backport request aside, and # `cancel-in-progress` stops one that IS from cancelling rather than queuing. # Both are load-bearing. `backport` and `backport-previous` are separate requests # that both have to complete, so they share the main group and must not cancel # each other; every other label does no work here and only has to stay out of # the way. # # That is also why this file does not simply copy pull-requests.yaml, which # splits the key and leaves cancellation unconditional: a discarded label run # there publishes nothing, so isolating it is the whole fix. # # Queuing protects a pending run from the run ahead of it and never from the one # behind: the group holds a single pending run, and a newer one evicts it. With # the split in place that costs nothing, and for the same reason the fan-out # below is harmless — the only events left in this group are backport requests, # the evictor is by definition the newer of the two, and `prepare`'s `Check which # labels are present` step reads the cumulative label set. So the survivor covers # a superset of what the evicted run would have delivered, for any sequence that # only adds labels. Removing one in between is the exception and needs no cover: # the evictor then carries less because the request was withdrawn. # # That is exactly what the split buys. Without it the evictor could be any label # at all, and a run that does not qualify delivers nothing in place of the # request it displaced. # # `queue: max` raises the single pending slot to a hundred and is the obvious # thing to reach for instead of the split. Taking it means giving up the # conditional cancel, because `queue: max` and `cancel-in-progress: true` are a # validation error together and this key still evaluates to true on a merge. # The trade is available and was not taken: eviction is what keeps a burst to one # surviving run rather than a hundred queued ones, and the feature only shipped # 2026-05-07, on a path that delivers fixes to release lines. concurrency: group: backport-${{ github.workflow }}-${{ github.event.pull_request.number }}${{ (github.event.action == 'labeled' && github.event.label.name != 'backport' && github.event.label.name != 'backport-previous' && github.event.label.name != 'kind/backport' && github.event.label.name != 'kind/backport-previous') && '-label' || '' }} # Stated positively, matching the group key above. `!= 'labeled'` is equivalent # only while `types:` holds exactly these two, and that form fails open: adding # `unlabeled` or `reopened` there would hand those events cancellation in the # main group, which is the behaviour this file exists to remove. # # The positive form removes the cancelling, not the occupying. A third type # still lands in the main group, still takes its single pending slot, and its # `prepare` still skips — so it can evict a genuine backport request and # deliver nothing in its place. `types:` is load-bearing for that reason and is # pinned in hack/release-freeze-contract.bats; widening it needs the group key # widened with it. cancel-in-progress: ${{ github.event.action == 'closed' }} # Top-level token defaults to read-only. A job-level block replaces this one # rather than adding to it, so each job restates every scope it needs. permissions: contents: read jobs: # Determine which backports are needed prepare: # This guard admits each action on the labels it is entitled to. `closed` # carries no label of its own, so it reads the set the PR ended up with. # `labeled` reads only the label just added: matching the cumulative set # here means every later unrelated label on a merged PR that still carries # `backport` re-enters this job to redo a backport already delivered. # # Scope, so this is not read as covering the whole job: the `Check which # labels are present` step below still reads the cumulative set, so a # `backport-previous` event on a PR also carrying `backport` fans out to # both matrix legs. That is deliberate, and each state a re-entered leg can # find is already accounted for: delivered is skipped by the merged-backport # guard, still open is skipped by backport-action on the 422, and closed # unmerged gets a fresh backport PR, which is the retry that guard # deliberately preserves rather than an accident. What the narrowing here # decides is whether the job RUNS, not which targets it picks. if: | github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main' && ( (github.event.action == 'closed' && (contains(github.event.pull_request.labels.*.name, 'backport') || contains(github.event.pull_request.labels.*.name, 'backport-previous') || contains(github.event.pull_request.labels.*.name, 'kind/backport') || contains(github.event.pull_request.labels.*.name, 'kind/backport-previous'))) || (github.event.action == 'labeled' && (github.event.label.name == 'backport' || github.event.label.name == 'backport-previous' || github.event.label.name == 'kind/backport' || github.event.label.name == 'kind/backport-previous')) ) # GitHub API calls only — no docker, no repo toolchain: GitHub-hosted. runs-on: ubuntu-latest # Queuing gives a stuck run a way to hurt the next one that a cancelling key # did not: the label event that used to kill it now waits behind it rather # than clearing it. # # This ceiling bounds a stuck JOB, which is the case it can reach. A run can # also wedge at the RUN level with every job already finished, and no # job-level key expires that one; it holds the group until GitHub retires the # run. Rare but real: run 31232645133 has been `in_progress` since # 2026-08-08 with `prepare` and `backport` both skipped. Nothing here # reaches that state, so docs/release.md tells an operator to look for a run # still in flight and clear it before re-applying the label. # # What it bounds is EXECUTION, not the wait for a runner. GitHub's limits # page says "job execution time" for the 6-hour job cap while spelling out # that the 35-day run cap "includes execution duration, and time spent on # waiting and approval" — the contrast is deliberate — and # orgs/community#50926 shows a job sitting six hours on "Waiting for a runner # to pick up this job" under `timeout-minutes: 5`. So queue time is a third # unbounded case alongside the run-level wedge, not something this covers. # # 30 is therefore generous rather than calculated. Execution on run # 29844315422 was 6s for `prepare` and 2s and 16s for the two matrix legs, # against 9m24s, 5m28s and 5m45s of queue for the same three jobs. Every # execution measured on this workflow has been seconds, and no maximum is # quoted on purpose: an absolute maximum over a growing set is stale as soon # as a slower run lands. The value leaves room for a cherry-pick far larger # than anything seen while replacing the 6-hour default, and nothing here is # sized against the queue because nothing here can be. timeout-minutes: 30 permissions: contents: read outputs: backport_current: ${{ steps.labels.outputs.backport }} backport_previous: ${{ steps.labels.outputs.backport_previous }} current_branch: ${{ steps.branches.outputs.current_branch }} previous_branch: ${{ steps.branches.outputs.previous_branch }} steps: - name: Check which labels are present id: labels uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 with: script: | const pr = context.payload.pull_request; const labels = pr.labels.map(l => l.name); // TRANSITIONAL: both spellings are accepted so the rename can land // in any order relative to the org-level dosubot, which still // applies the legacy names and is today the dominant applier on // real backports. Once dosubot's PR labelling is switched off and // the in-repo labeler is the only applier, the legacy arms here, // in the `if:` gate above and in the concurrency group can all be // deleted in one pass. const isBackport = labels.includes('kind/backport') || labels.includes('backport'); const isBackportPrevious = labels.includes('kind/backport-previous') || labels.includes('backport-previous'); core.setOutput('backport', isBackport ? 'true' : 'false'); core.setOutput('backport_previous', isBackportPrevious ? 'true' : 'false'); console.log(`backport label: ${isBackport}, backport-previous label: ${isBackportPrevious}`); - name: Determine target branches id: branches uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 with: script: | // Enumerate the real release-X.Y branches rather than deriving them // from the latest published release. // // Since cutting an rc freezes the line (cut-prerelease.yaml), // release-X.Y is created when the first vX.Y.0-rc.N is cut — before // vX.Y.0 is ever published. getLatestRelease returns the newest // published STABLE, so throughout the freeze window it still named // the previous line: a `backport` on a fix for the release being // stabilised would have landed on release-X.(Y-1) and missed the // release it was written for. That window is exactly when backports // matter most, since the frozen branch is the only way in. // // Enumerating branches also drops the contiguous-minor assumption: // `previous` used to be computed as min-1, which named a // non-existent branch whenever a minor was skipped. const branches = await github.paginate(github.rest.repos.listBranches, { owner: context.repo.owner, repo: context.repo.repo, per_page: 100 }); const lines = branches .map(b => /^release-(\d+)\.(\d+)$/.exec(b.name)) .filter(Boolean) .map(m => ({ name: m[0], maj: Number(m[1]), min: Number(m[2]) })) .sort((a, b) => (b.maj - a.maj) || (b.min - a.min)); if (lines.length === 0) { core.setFailed('No release-X.Y branches found; cannot determine backport target.'); return; } const currentBranch = lines[0].name; const previousBranch = lines.length > 1 ? lines[1].name : ''; core.setOutput('current_branch', currentBranch); core.setOutput('previous_branch', previousBranch); console.log(`Release lines found: ${lines.map(l => l.name).join(', ')}`); console.log(`Current branch: ${currentBranch}, Previous branch: ${previousBranch || 'N/A'}`); // Both targets come from the enumeration above, so they exist by // construction — no getBranch probe needed. What CAN still fail is // asking for a previous line when only one exists. if (!previousBranch && '${{ steps.labels.outputs.backport_previous }}' === 'true') { core.setFailed('backport-previous requested, but only one release line exists.'); return; } backport: needs: prepare if: | github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main' && (needs.prepare.outputs.backport_current == 'true' || needs.prepare.outputs.backport_previous == 'true') # git cherry-picks via backport-action — no docker, no repo toolchain: GitHub-hosted. runs-on: ubuntu-latest # See `prepare` above: a queued request waits on this one, so it needs a # ceiling rather than the 6-hour default. Bounds this job's execution only; # the wait for a runner is outside it either way. timeout-minutes: 30 permissions: contents: write pull-requests: write strategy: matrix: backport_type: [current, previous] steps: # 1. Determine target branch based on matrix - name: Set target branch id: target if: | (matrix.backport_type == 'current' && needs.prepare.outputs.backport_current == 'true') || (matrix.backport_type == 'previous' && needs.prepare.outputs.backport_previous == 'true') run: | if [ "${{ matrix.backport_type }}" == "current" ]; then echo "branch=${{ needs.prepare.outputs.current_branch }}" >> $GITHUB_OUTPUT echo "Target branch: ${{ needs.prepare.outputs.current_branch }}" else echo "branch=${{ needs.prepare.outputs.previous_branch }}" >> $GITHUB_OUTPUT echo "Target branch: ${{ needs.prepare.outputs.previous_branch }}" fi # 2. Skip if this target already has a merged backport. # # The action's backport branch name is deterministic, # backport--to-. A merged PR with that head # means an earlier run already delivered this change to the target — a # second label event (e.g. backport-previous added after backport # already merged) would re-enter this job and cherry-pick commits the # target branch already has. Git reports that as an empty pick (exit 1) # rather than a conflict, which draft_commit_conflicts below misreads # as a real conflict and reports as a failed backport on the original # PR. Skipping here avoids the false report; it does not touch the # empty-pick behavior itself, which lives in the action. - name: Check for existing merged backport id: guard if: steps.target.outcome == 'success' uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 with: script: | const targetBranch = '${{ steps.target.outputs.branch }}'; const head = `backport-${context.payload.pull_request.number}-to-${targetBranch}`; const { data: prs } = await github.rest.pulls.list({ owner: context.repo.owner, repo: context.repo.repo, state: 'closed', head: `${context.repo.owner}:${head}`, }); const alreadyMerged = prs.some(p => p.merged_at !== null); core.setOutput('already_merged', alreadyMerged ? 'true' : 'false'); if (alreadyMerged) { console.log(`Skipping backport to ${targetBranch}: ${head} already merged.`); } # 3. Checkout (required by backport‑action) - name: Checkout repository if: steps.target.outcome == 'success' && steps.guard.outputs.already_merged != 'true' uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 # 4. Create the back‑port pull request - name: Create back‑port PR id: backport if: steps.target.outcome == 'success' && steps.guard.outputs.already_merged != 'true' uses: korthout/backport-action@0193454f0c5947491d348f33a275c119f30eb736 # v3.2.1 with: github_token: ${{ secrets.GITHUB_TOKEN }} label_pattern: '' # don't read labels for targets target_branches: ${{ steps.target.outputs.branch }} merge_commits: skip # conflict_resolution lives inside the experimental JSON input, not as a # top-level key. Passed top-level it is silently ignored and the action # falls back to the experimental default ("fail"), which on a conflict # creates no PR and only comments. Nesting it here makes a conflicting # backport open a draft PR with the conflict committed for manual fixup. experimental: | { "conflict_resolution": "draft_commit_conflicts" }