Redesign backport automation around port-commit --from-pr

Move all backport label parsing, per-base looping, idempotency, and error
aggregation into ddev release port-commit --from-pr, backed by unit tests.
Slim backport-pr.yml to a should_run gate job plus a gated backport job, and
use ddev config override in place of the repo-pointing config set calls.

Author: Kyle-Neale

.github/workflows/backport-pr.yml

@@ -6,14 +6,12 @@ on:
       - labeled
 
 jobs:
-  backport:
-    name: Backport PR
+  check:
+    name: Check for backport labels
     runs-on: ubuntu-latest
-    permissions:
-      id-token: write  # OIDC token federation with dd-octo-sts
-      # Writes use the scoped octo-sts token; ambient GITHUB_TOKEN stays read-only (pull_request_target).
-      contents: read
-      pull-requests: read
+    # Cheap event filter: only merged PRs, and only the `closed` event or a freshly-added
+    # `backport/*` label. `should_run` below is the label-presence semaphore that gates the
+    # expensive backport job.
     if: >
       github.event.pull_request.merged
       && (
@@ -23,6 +21,33 @@ jobs:
           && startsWith(github.event.label.name, 'backport/')
         )
       )
+    permissions:
+      contents: read
+    outputs:
+      should_run: ${{ steps.gate.outputs.should_run }}
+    steps:
+      - name: Detect backport labels
+        id: gate
+        env:
+          PR_LABELS_JSON: ${{ toJSON(github.event.pull_request.labels.*.name) }}
+        run: |
+          set -euo pipefail
+          if printf '%s' "${PR_LABELS_JSON}" | jq -e 'any(.[]; startswith("backport/"))' >/dev/null; then
+            echo "should_run=true" >> "${GITHUB_OUTPUT}"
+          else
+            echo "should_run=false" >> "${GITHUB_OUTPUT}"
+          fi
+
+  backport:
+    name: Backport PR
+    needs: check
+    if: needs.check.outputs.should_run == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # OIDC token federation with dd-octo-sts
+      # Writes use the scoped octo-sts token; ambient GITHUB_TOKEN stays read-only (pull_request_target).
+      contents: read
+      pull-requests: read
     steps:
       - name: Get GitHub token via dd-octo-sts
         uses: DataDog/dd-octo-sts-action@acaa02eee7e3bb0839e4272dacb37b8f3b58ba80 # v1.0.3
@@ -34,7 +59,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          # Full history reaches the merged commit and release branches; octo-sts token authenticates the push.
+          # Full history reaches the merged commit and every release branch; octo-sts token authenticates the push.
           fetch-depth: 0
           token: ${{ steps.octo-sts.outputs.token }}
 
@@ -52,92 +77,20 @@ jobs:
       - name: Configure ddev
         run: |
           ddev config set upgrade_check false
-          ddev config set repos.core .
-          ddev config set repo core
+          ddev config override
+
+      - name: Configure git identity
+        run: |
+          git config --global user.name "dd-agent-integrations-bot[bot]"
+          git config --global user.email "dd-agent-integrations-bot[bot]@users.noreply.github.com"
 
       - name: Backport merged PR to labelled branches
         env:
-          EVENT_ACTION: ${{ github.event.action }}
-          LABEL_NAME: ${{ github.event.label.name }}
-          PR_LABELS_JSON: ${{ toJSON(github.event.pull_request.labels.*.name) }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
-          REPO: ${{ github.repository }}
-          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
           # ddev reads the token/user from these; the same token authenticates git push via checkout.
           DD_GITHUB_TOKEN: ${{ steps.octo-sts.outputs.token }}
           GH_TOKEN: ${{ steps.octo-sts.outputs.token }}
           DD_GITHUB_USER: dd-agent-integrations-bot
         run: |
-          set -euo pipefail
-
-          # Best-effort PR comment; a comment failure must never fail the backport.
-          comment_pr() { gh pr comment "${PR_NUMBER}" --repo "${REPO}" --body "$1" || true; }
-
-          if [ -z "${MERGE_SHA}" ]; then
-            echo "::error::merge_commit_sha is empty; cannot backport."
-            exit 1
-          fi
-
-          # Target branches come from backport/<base> labels: only the new one on `labeled`, all of them on `closed`.
-          bases=()
-          if [ "${EVENT_ACTION}" = "labeled" ]; then
-            case "${LABEL_NAME}" in
-              backport/*) bases+=("${LABEL_NAME#backport/}") ;;
-              *) echo "Label '${LABEL_NAME}' is not a backport label; nothing to do."; exit 0 ;;
-            esac
-          else
-            while IFS= read -r base; do
-              [ -n "${base}" ] && bases+=("${base}")
-            done < <(printf '%s' "${PR_LABELS_JSON}" | jq -r '.[] | select(startswith("backport/")) | ltrimstr("backport/")')
-          fi
-
-          if [ "${#bases[@]}" -eq 0 ]; then
-            echo "No backport/* labels to process."
-            exit 0
-          fi
-
-          git config --global user.name "dd-agent-integrations-bot[bot]"
-          git config --global user.email "dd-agent-integrations-bot[bot]@users.noreply.github.com"
-
-          sha10="${MERGE_SHA:0:10}"
-          overall_rc=0
-          for base in "${bases[@]}"; do
-            # Mirror port-commit's branch naming so we can detect an existing backport before doing work.
-            branch="$(printf '%s' "${DD_GITHUB_USER}/backport-${sha10}-to-${base}" | tr '[:upper:]' '[:lower:]')"
-
-            # Only an OPEN backport PR is detected. A branch left by a failed prior run (no open PR) is not
-            # auto-cleaned; port-commit's push then fails non-fast-forward until the stale branch is deleted manually.
-            if [ -n "$(gh pr list --repo "${REPO}" --head "${branch}" --state open --json number --jq '.[].number')" ]; then
-              echo "::notice::Backport to ${base} already has an open PR (branch ${branch}); skipping."
-              continue
-            fi
-
-            # Ensure origin/<base> exists locally for the worktree; a missing branch fails just this base, not the run.
-            if ! git fetch --no-tags origin "+refs/heads/${base}:refs/remotes/origin/${base}"; then
-              echo "::error::Target branch ${base} does not exist on origin; skipping."
-              comment_pr "⚠️ Automatic backport to \`${base}\` skipped: the target branch does not exist."
-              overall_rc=1
-              continue
-            fi
-
-            echo "::group::Backport #${PR_NUMBER} to ${base}"
-            # Pass the merge SHA we already have rather than PR-<n>, which would round-trip via the API back to this commit.
-            if ddev --no-interactive release port-commit "${MERGE_SHA}" \
-                 --target-branch "${base}" \
-                 --branch-prefix backport \
-                 --pr-labels "backport,bot"; then
-              pr_url="$(gh pr list --repo "${REPO}" --head "${branch}" --state open --json url --jq '.[0].url // ""' || true)"
-              echo "::notice::Opened backport PR for ${base}: ${pr_url}"
-              if [ -n "${pr_url}" ]; then
-                comment_pr "Backport to \`${base}\` opened: ${pr_url}"
-              fi
-            else
-              echo "::error::Backport to ${base} failed."
-              comment_pr "⚠️ Automatic backport to \`${base}\` failed. See the [workflow run](${RUN_URL}) for details, or backport manually with \`ddev release port-commit PR-${PR_NUMBER} --target-branch ${base}\`. If the push was rejected as non-fast-forward, delete the stale \`${branch}\` branch and retry."
-              overall_rc=1
-            fi
-            echo "::endgroup::"
-          done
-
-          exit "${overall_rc}"
+          ddev --no-interactive release port-commit --from-pr "${{ github.event.pull_request.number }}" \
+            --branch-prefix backport \
+            --pr-labels backport,bot

ddev/changelog.d/24470.added

@@ -1 +1,2 @@
+`release port-commit --from-pr <number>` backports a merged PR to every `backport/<base>` label on it, deriving the commit and target branches from the PR and skipping bases whose backport PR already exists.
 `release port-commit` now resets `.deps/` in addition to `.in-toto` when porting a commit, so resolved dependency lockfiles are taken from the target branch.

ddev/src/ddev/cli/release/port_commit.py

@@ -28,6 +28,15 @@
 @click.option('--draft', is_flag=True, default=False, help='Open the PR as a draft.')
 @click.option('--verify', is_flag=True, default=False, help='Run commit hooks (skipped by default).')
 @click.option('--dry-run', is_flag=True, default=False, help='Print every step instead of executing it.')
+@click.option(
+    '--from-pr',
+    'from_pr',
+    type=int,
+    default=None,
+    metavar='PR_NUMBER',
+    help='Backport a merged PR to every `backport/<base>` label on it, deriving the commit and target '
+    'branches from the PR. Mutually exclusive with COMMIT_OR_PR.',
+)
 def port_commit(
     app: Application,
     commit_hash: str | None,
@@ -39,6 +48,7 @@ def port_commit(
     draft: bool,
     verify: bool,
     dry_run: bool,
+    from_pr: int | None,
 ) -> None:
     """
     Backport a commit onto a target branch.
@@ -53,22 +63,52 @@ def port_commit(
     first when a GitHub token is configured, and fall back to commit resolution on 404. If
     omitted, the current HEAD commit is used after confirmation.
 
+    Pass `--from-pr <number>` instead of COMMIT_OR_PR to backport a merged PR to every
+    `backport/<base>` label on it, deriving the commit and target branches from the PR. A base
+    whose backport PR already exists (open, merged, or closed) is skipped, so re-runs are
+    idempotent. Give `--target-branch` alongside `--from-pr` to restrict the backport to that one
+    branch.
+
     The GitHub user for the branch prefix is taken from `ddev config` (`github.user`) or the
     `DD_GITHUB_USER` / `GITHUB_USER` / `GITHUB_ACTOR` environment variables.
     """
     import logging
 
     from ddev.cli.release.port_commit_workflow import (
-        PortStepError,
-        build_port_steps,
         display_completion_summary,
+        execute_port_plan,
         resolve_port_plan,
+        run_backport_from_pr,
     )
 
     # httpx logs every request at INFO and clutters the workflow output. The PR-resolution and
     # PR-creation steps already print their own status lines; the underlying HTTP traffic is noise.
     logging.getLogger('httpx').setLevel(logging.WARNING)
 
+    if from_pr is not None:
+        if commit_hash is not None:
+            app.abort('Pass either COMMIT_OR_PR or --from-pr, not both.')
+        from click.core import ParameterSource
+
+        ctx = click.get_current_context()
+        target_branch_explicit = ctx.get_parameter_source('target_branch') is not ParameterSource.DEFAULT
+        succeeded = run_backport_from_pr(
+            app,
+            pr_number=from_pr,
+            target_branch=target_branch,
+            target_branch_explicit=target_branch_explicit,
+            branch_prefix=branch_prefix,
+            branch_suffix=branch_suffix,
+            pr_labels=pr_labels,
+            no_pr=no_pr,
+            draft=draft,
+            verify=verify,
+            dry_run=dry_run,
+        )
+        if not succeeded:
+            app.abort('One or more backports failed.')
+        return
+
     plan = resolve_port_plan(
         app,
         commit_hash=commit_hash,
@@ -81,36 +121,13 @@ def port_commit(
         verify=verify,
         dry_run=dry_run,
     )
-    bundle = build_port_steps(app, plan)
-
-    success = False
-    error_msg: str | None = None
-    try:
-        for step in bundle.steps:
-            step.run()
-        success = True
-    except PortStepError as e:
-        error_msg = str(e)
-    finally:
-        # If the PR was created before the failure (e.g. labeling failed afterwards), the worktree
-        # holds no recoverable state — the work is pushed and the PR exists on GitHub. Suppress the
-        # warning in that case to avoid a misleading "inspect the worktree" message.
-        pr_already_created = bundle.pr_step is not None and bundle.pr_step.pr_url is not None
-        if not success and not plan.dry_run and not pr_already_created:
-            app.display_warning(f'Worktree left at `{plan.worktree_path}` for inspection.')
-
-    if error_msg is not None:
-        app.abort(error_msg)
-
-    try:
-        bundle.teardown.run()
-    except PortStepError as e:
-        app.display_warning(f'Could not remove worktree at `{plan.worktree_path}`: {e}')
-        app.display_warning(f'Run `git worktree remove --force {plan.worktree_path}` to clean it up manually.')
+
+    outcome = execute_port_plan(app, plan)
+    if outcome.error is not None:
+        app.abort(outcome.error)
 
     if plan.dry_run:
         app.display_success('Dry run complete.')
         return
 
-    pr_url = bundle.pr_step.pr_url if bundle.pr_step is not None else None
-    display_completion_summary(app, plan, pr_url=pr_url)
+    display_completion_summary(app, plan, pr_url=outcome.pr_url)