backmerge.yml

name: back-merge main into develop

# Runs after the release workflow finishes. Pushes a branch at main's tip so the
# post-release state of main (changelog + tag lineage) can be merged back into develop.
#
# NOT triggered by `release: published`, despite that being the obvious choice. release.yml
# creates the release with `gh release create` under the default GITHUB_TOKEN, and GitHub
# suppresses workflow triggers for events raised by that token — so a `release` trigger
# never fires. It never fired for v2.2.0 or v2.3.0 either; both back-merges were done by
# hand. `workflow_run` is not subject to that suppression, so it is used instead.
#
# Like prepare-release, this workflow deliberately does NOT open the pull request. A PR
# opened by github-actions[bot] with the default GITHUB_TOKEN does not trigger the
# `pull_request` workflows (CI, Integration Tests, Commit Lint) that gate `develop`, so
# the back-merge would land unverified. The job summary carries a prefilled link instead.
#
# Unlike prepare-release, the PR body is one boilerplate sentence rather than an embedded
# changelog, so it fits in the URL and is prefilled too — there is nothing to copy and no
# reason to commit a body file.

on:
  workflow_run:
    workflows: ["comlink-python release"]
    types: [completed]
  # Manual escape hatch: lets a maintainer stage the back-merge without cutting a release,
  # and makes the workflow testable without waiting for one.
  workflow_dispatch:

permissions:
  contents: write

jobs:
  backmerge:
    runs-on: ubuntu-latest
    # workflow_run fires on completion regardless of outcome — only stage a back-merge
    # when the release actually succeeded.
    if: >-
      github.event_name == 'workflow_dispatch' ||
      github.event.workflow_run.conclusion == 'success'
    steps:
      - uses: actions/checkout@v7
        with:
          ref: main
          fetch-depth: 0

      - name: Stage the back-merge branch
        id: stage
        run: |
          set -euo pipefail
          # Nothing to back-merge if develop already contains every commit on main —
          # which is the normal state when the release PR was a fast-forward promotion.
          git fetch --no-tags --quiet origin develop
          if [ "$(git rev-list --count FETCH_HEAD..HEAD)" -eq 0 ]; then
            echo "needed=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          branch="backmerge/main-to-develop-${{ github.run_id }}"
          git config user.name  "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git switch -c "${branch}"
          git push origin "${branch}"

          echo "needed=true" >> "$GITHUB_OUTPUT"
          echo "branch=${branch}" >> "$GITHUB_OUTPUT"

      - name: Summarise how to open the back-merge PR
        run: |
          set -euo pipefail
          if [ "${{ steps.stage.outputs.needed }}" != "true" ]; then
            {
              printf '## No back-merge needed\n\n'
              printf '`develop` already contains every commit on `main`. No branch was pushed.\n'
            } >> "$GITHUB_STEP_SUMMARY"
            exit 0
          fi

          branch="${{ steps.stage.outputs.branch }}"
          title="chore: back-merge main into develop"
          body="Post-release sync of \`main\` (changelog + tag lineage) back into \`develop\`."
          encoded_title="$(jq -rn --arg t "${title}" '$t|@uri')"
          encoded_body="$(jq -rn --arg b "${body}" '$b|@uri')"
          url="${{ github.server_url }}/${{ github.repository }}/compare/develop...${branch}?expand=1&title=${encoded_title}&body=${encoded_body}"

          {
            printf '## Back-merge is staged\n\n'
            printf 'Branch `%s` is pushed. Open the PR manually — a bot-authored PR would not run the `pull_request` checks that gate `develop`.\n\n' "${branch}"
            printf '### [→ Open the back-merge PR](%s)\n\n' "${url}"
            printf 'Title and body are prefilled. Base `develop`, head `%s`.\n' "${branch}"
          } >> "$GITHUB_STEP_SUMMARY"