ADR Suggestion Automated backmerge from master to develop on release tags

[AndrewSazonov]

The overall branching strategy is described in a separate ADR:
https://github.com/orgs/easyscience/discussions/12

Across EasyScience repositories, we follow a feature → develop → master workflow. After a release, master may contain changes that also need to be applied back to develop (for example, quick fixes or version bumps), so that any new feature branches are created from an up-to-date develop.

This “backmerge” step from master to develop is easy to forget and often involves extra manual work. As a result, develop can fall behind master, which may lead to confusion and inconsistencies in subsequent development.

Proposal

Add a standard workflow to the EasyScience Copier templates that automatically merges master into develop whenever a new release tag (v*) is pushed.

Key behavior:

• Triggered on push of tags matching v* (and optionally via workflow_dispatch)
• Performs a direct merge from origin/master into develop (no PR)
• Adds [skip ci] to the merge commit message to avoid re-running CI unnecessarily
• Uses the EasyScience GitHub App token so the merge can bypass branch rules safely
• Exits cleanly if develop is already up-to-date with master

Proposed workflow (to be included in templates)

# This workflow automatically merges `master` into `develop` whenever a
# new version tag is pushed (v*).
#
# Key points:
# - Directly merges master into develop without creating a PR.
# - Skips CI on the merge commit using [skip ci] in the commit message.
# - The code being merged has already been tested as part of the release process.
# - This ensures develop stays up-to-date with release changes (version bumps, etc.).
#
# Required organization config:
# https://github.com/organizations/easyscience/settings/secrets/actions
# https://github.com/organizations/easyscience/settings/variables/actions
# - Actions secret:   EASYSCIENCE_APP_KEY  (GitHub App private key PEM)
# - Actions variable: EASYSCIENCE_APP_ID   (GitHub App ID)
#
# IMPORTANT:
# The GitHub App must be added to the develop branch ruleset bypass list.

name: Backmerge (master -> develop)

on:
  push:
    tags: ['v*']
  workflow_dispatch:

permissions:
  contents: write

jobs:
  backmerge:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository (for local actions)
        uses: actions/checkout@v5

      - name: Setup easyscience[bot]
        id: bot
        uses: ./.github/actions/setup-easyscience-bot
        with:
          app-id: ${{ vars.EASYSCIENCE_APP_ID }}
          private-key: ${{ secrets.EASYSCIENCE_APP_KEY }}
          repositories: ${{ github.event.repository.name }}

      - name: Checkout repository (with bot token)
        uses: actions/checkout@v5
        with:
          fetch-depth: 0
          token: ${{ steps.bot.outputs.token }}

      - name: Configure git identity
        run: |
          git config user.name "easyscience[bot]"
          git config user.email "${{ vars.EASYSCIENCE_APP_ID }}+easyscience[bot]@users.noreply.github.com"

      - name: Merge master into develop
        run: |
          set -euo pipefail

          echo "Fetching develop branch"
          git fetch origin develop:develop

          echo "Switching to develop branch"
          git checkout develop

          echo "Checking if already up-to-date"
          if git merge-base --is-ancestor origin/master develop; then
            echo "ℹ️ Develop is already up-to-date with master"
            exit 0
          fi

          echo "Preparing merge message"
          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
            MESSAGE="Backmerge: master into develop (manual) [skip ci]"
          else
            TAG="${{ github.ref_name }}"
            MESSAGE="Backmerge: ${TAG} from master into develop [skip ci]"
          fi

          echo "Merging master into develop"
          git merge origin/master --no-ff -m "${MESSAGE}"

          echo "Pushing to develop"
          git push origin develop

          echo "✅ Successfully merged master into develop"

[rozyczko]

What happens when the merge fails? The workflow uses set -euo pipefail which will fail hard on conflicts, but:

• There's no notification mechanism when this happens
• No issue gets created to alert maintainers
• The workflow just silently fails
• Someone has to notice the failed action in the Actions tab

We NEED a conflict handling strategy.

We also assume nobody pushes to develop while this action is taking place... probably a good assumption but maybe we can add --force-with-lease or retry on push failure?

Another thing is - should this be triggered on tag push? At this time, the release workflow may still be running. If this workflow makes additional changes to master (changelog, version bump, whatever), those won't be backmerged.
Maybe trigger this on release: published instead?

[AndrewSazonov]

I agree, we definitely need a clear conflict-handling strategy. What I shared was meant as a first draft to show the idea and get feedback. I’d be happy to hear concrete suggestions on how to improve the Merge master into develop step, especially around conflict handling and notifications.

About the trigger: I initially chose on: tag push because, in the workflow I had in mind, no additional changes are supposed to happen on master after tagging - no changelog updates, no version bumps, etc. In that case, backmerging immediately on tag creation should be fine and works as expected in the tested repository (diffraction-lib).

That said, on: release: published does indeed look safer. One open question for me is how this behaves for pre-releases: as far as I understand, release: published does not trigger for pre-releases by default, so we would need to account for that explicitly if we want the same behavior for them as well?

[rozyczko]

we definitely need a clear conflict-handling strategy

something like this added to the yaml? So at least we are notified about the issues.

- name: Merge master into develop
  id: merge
  continue-on-error: true
  run: |
    git merge origin/master --no-ff -m "${MESSAGE}" || echo "conflict=true" >> $GITHUB_OUTPUT

- name: Create issue on conflict
  if: steps.merge.outputs.conflict == 'true'
  uses: actions/github-script@v8
  with:
    script: |
      await github.rest.issues.create({
        owner: context.repo.owner,
        repo: context.repo.repo,
        title: 'Backmerge conflict: master → develop',
        body: 'Automatic backmerge failed due to conflicts. Manual resolution required.',
        labels: ['backmerge', 'conflict']
      })