# Automatically backport merged PRs to every actively supported release branch
# when the "backport" label is applied. Works whether the label is added before
# or after the PR is merged.
#
# Target branches are the union of:
#   - the latest 3 release/2.X branches (mainline, stable, security), and
#   - the active ESR / ESR-1 branches listed in
#     scripts/release_channels/esr_versions.txt.
# The set is de-duplicated, so a branch that is both stable and ESR is
# backported once.
#
# Usage:
#   1. Add the "backport" label to a PR targeting main.
#   2. When the PR merges (or if already merged), the workflow detects the
#      target release/* branches and opens one cherry-pick PR per branch.
#
# The created backport PRs follow existing repo conventions:
#   - Branch:  backport/<pr>-to-<version>
#   - Title:   <original PR title> (#<pr>)
#   - Body:    links back to the original PR and merge commit
#   - Label:   backport/v<version> to identify the target release

name: Backport
on:
  pull_request_target:
    branches:
      - main
    types:
      - closed
      - labeled

permissions: {}

# Prevent duplicate runs for the same PR when both 'closed' and 'labeled'
# fire in quick succession.
concurrency:
  group: backport-${{ github.event.pull_request.number }}

jobs:
  detect:
    name: Detect target branches
    permissions:
      contents: read
    if: >
      github.event.pull_request.merged == true &&
      contains(github.event.pull_request.labels.*.name, 'backport')
    runs-on: ubuntu-latest
    outputs:
      branches: ${{ steps.find.outputs.branches }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          # Need all refs to discover release branches.
          fetch-depth: 0
          persist-credentials: false

      - name: Find target release branches
        id: find
        env:
          ESR_VERSIONS_FILE: scripts/release_channels/esr_versions.txt
        run: |
          set -euo pipefail

          # Mainline, stable, security: the latest 3 release/2.X branches
          # (exact pattern, no suffixes like release/2.31_hotfix), sorted by
          # minor version descending.
          TOP3=$(
            git branch -r \
              | grep -E '^\s*origin/release/2\.[0-9]+$' \
              | sed 's|.*origin/||' \
              | sort -t. -k2 -n -r \
              | head -3
          )

          # ESR and ESR-1: the active ESR versions from the shared source of
          # truth. Each entry maps to the release/<version> branch. Skip
          # entries whose branch does not exist.
          ESR_BRANCHES=""
          if [ -f "$ESR_VERSIONS_FILE" ]; then
            while read -r RELEASE; do
              BRANCH="release/${RELEASE}"
              if git show-ref --verify --quiet "refs/remotes/origin/${BRANCH}"; then
                ESR_BRANCHES="${ESR_BRANCHES}${BRANCH}"$'\n'
              else
                echo "::warning::ESR branch ${BRANCH} not found, skipping."
              fi
            done < <(grep -vE '^\s*(#|$)' "$ESR_VERSIONS_FILE")
          else
            echo "::warning::${ESR_VERSIONS_FILE} not found, backporting to latest 3 only."
          fi

          # Union the two sets and de-duplicate.
          BRANCHES=$(printf '%s\n%s\n' "$TOP3" "$ESR_BRANCHES" | sed '/^$/d' | sort -u)

          if [ -z "$BRANCHES" ]; then
            echo "No release branches found."
            echo "branches=[]" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          # Convert to JSON array for the matrix.
          JSON=$(echo "$BRANCHES" | jq -Rnc '[inputs | select(length > 0)]')
          echo "branches=$JSON" >> "$GITHUB_OUTPUT"
          echo "Will backport to: $JSON"

  backport:
    name: "Backport to ${{ matrix.branch }}"
    needs: detect
    permissions:
      contents: write
      pull-requests: write
      # Required to create the release-specific backport label if missing.
      issues: write
    if: needs.detect.outputs.branches != '[]'
    runs-on: ubuntu-latest
    strategy:
      matrix:
        branch: ${{ fromJson(needs.detect.outputs.branches) }}
      fail-fast: false
    env:
      PR_NUMBER: ${{ github.event.pull_request.number }}
      PR_TITLE: ${{ github.event.pull_request.title }}
      PR_URL: ${{ github.event.pull_request.html_url }}
      MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
      SENDER: ${{ github.event.sender.login }}
      BRANCH: ${{ matrix.branch }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          # Full history required for cherry-pick.
          fetch-depth: 0
          persist-credentials: false

      - name: Cherry-pick and open PR
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail

          # Configure git to authenticate pushes with the job token
          # since persist-credentials is disabled on checkout.
          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"

          RELEASE_VERSION="$BRANCH"
          # Strip the release/ prefix for naming.
          VERSION="${RELEASE_VERSION#release/}"
          BACKPORT_BRANCH="backport/${PR_NUMBER}-to-${VERSION}"

          # Label applied to the backport PR so PRs for a specific release can
          # be filtered easily (e.g. backport/v2.34).
          BACKPORT_LABEL="backport/v${VERSION}"

          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

          # Idempotency: if a backport PR already exists for this branch
          # (open, closed, or merged), there is nothing to do. This is the
          # primary guard so a re-run that previously pushed a branch but
          # failed before opening the PR still recovers below.
          EXISTING_PR=$(gh pr list --head "$BACKPORT_BRANCH" --base "$RELEASE_VERSION" --state all --json number --jq '.[0].number // empty')
          if [ -n "$EXISTING_PR" ]; then
            echo "PR #${EXISTING_PR} already exists for ${BACKPORT_BRANCH}, skipping."
            exit 0
          fi

          CONFLICTS=false
          if git ls-remote --exit-code origin "refs/heads/${BACKPORT_BRANCH}" >/dev/null 2>&1; then
            # The branch exists from an earlier run that failed before opening
            # the PR. Reuse it as-is and fall through to PR creation rather
            # than starting over or bailing out.
            echo "Backport branch ${BACKPORT_BRANCH} already exists; reusing it to open the PR."
          else
            # Create the backport branch from the target release branch.
            git checkout -b "$BACKPORT_BRANCH" "origin/${RELEASE_VERSION}"

            # Cherry-pick the merge commit. Use -x to record provenance and
            # -m1 to pick the first parent (the main branch side).
            #
            # Every target branch is validated to exist in the detect job, so a
            # failure here is a genuine conflict, not a missing branch. Rather
            # than abort the whole backport, leave a placeholder commit and open
            # a PR with copy-paste resolution steps so it can be finished by
            # hand (or closed) instead of recreated from scratch.
            if ! git cherry-pick -x -m1 "$MERGE_SHA"; then
              echo "::warning::Cherry-pick to ${RELEASE_VERSION} had conflicts."
              CONFLICTS=true

              # Abort the failed cherry-pick and create an empty commit
              # explaining the situation.
              git cherry-pick --abort
              git commit --allow-empty -m "Cherry-pick of #${PR_NUMBER} requires manual resolution

          The automatic cherry-pick of ${MERGE_SHA} to ${RELEASE_VERSION} had conflicts.
          Please cherry-pick manually:

              git cherry-pick -x -m1 ${MERGE_SHA}"
            fi

            git push origin "$BACKPORT_BRANCH"
          fi

          TITLE="${PR_TITLE} (#${PR_NUMBER})"
          BODY=$(cat <<EOF
          Backport of ${PR_URL}

          Original PR: #${PR_NUMBER} — ${PR_TITLE}
          Merge commit: ${MERGE_SHA}
          Requested by: @${SENDER}
          EOF
          )

          if [ "$CONFLICTS" = true ]; then
            TITLE="${TITLE} (conflicts)"
            BODY="${BODY}

          > [!WARNING]
          > The automatic cherry-pick had conflicts.
          > Please resolve manually by cherry-picking the original merge commit:
          >
          > \`\`\`
          > git fetch origin ${BACKPORT_BRANCH}
          > git checkout ${BACKPORT_BRANCH}
          > git reset --hard origin/${RELEASE_VERSION}
          > git cherry-pick -x -m1 ${MERGE_SHA}
          > # resolve conflicts, then push
          > \`\`\`"
          fi

          # Ensure the release-specific label exists. Best-effort: label
          # problems must never prevent the PR from being opened.
          gh label create "$BACKPORT_LABEL" \
            --description "Backport PR targeting ${RELEASE_VERSION}" \
            --color "D93F0B" \
            --force || echo "::warning::Could not create label ${BACKPORT_LABEL}."

          # Create the PR first, then attach label/assignee/reviewer
          # separately. Requesting a review from (or assigning) the PR author
          # is rejected by GitHub, and doing it inline with `gh pr create`
          # under `set -e` would abort the job and leave no PR. Attaching them
          # afterwards as best-effort guarantees the PR always gets created.
          NEW_PR_URL=$(
            gh pr create \
              --base "$RELEASE_VERSION" \
              --head "$BACKPORT_BRANCH" \
              --title "$TITLE" \
              --body "$BODY"
          )

          gh pr edit "$NEW_PR_URL" --add-label "$BACKPORT_LABEL" || echo "::warning::Could not add label ${BACKPORT_LABEL} to ${NEW_PR_URL}."
          gh pr edit "$NEW_PR_URL" --add-assignee "$SENDER" || echo "::warning::Could not assign @${SENDER} to ${NEW_PR_URL}."
          gh pr edit "$NEW_PR_URL" --add-reviewer "$SENDER" || echo "::warning::Could not request review from @${SENDER} on ${NEW_PR_URL}."

          # Notify the requester on the original PR which backport was opened,
          # flagging conflicts that still need manual resolution. Best-effort:
          # don't fail the job if the original PR is locked.
          COMMENT="Backport to \`${RELEASE_VERSION}\` created: ${NEW_PR_URL}"
          if [ "$CONFLICTS" = true ]; then
            COMMENT="${COMMENT} (:warning: conflicts need manual resolution)"
          fi
          gh pr comment "$PR_NUMBER" --body "$COMMENT" || echo "::warning::Failed to comment on #${PR_NUMBER} (PR may be locked)."