BackportBot

BackportBot handles backports

Behavior

The BackportBot assists in creating backport issues and automatically closing backport issues.

Creating Backport

The BackportBot can create issues in two different ways. In either case the following logic is used:

If backport issue does not exist:
Create a new backport issue with the additional label type: backport
Update the existing issue with the label status: backported
Automatically remove the for: backport-to-<branch-name> label from the existing issue

Via Labels

You can add a label in the form of for: backport-to-<branch-name> (i.e. for: backport-to-5.1.x) and adding the label to a ticket will create a backport for the branch <branch-name> (i.e. 5.1.x).

Pushing to Branch

You can create a backport by pushing to a branch that ends in .x with Fixes: gh-<number> in the commit message.

Closing Backport

If a branch ending in .x is pushed to, the BackportBot will look at the commit message for the pattern Fixes: gh-<number>. If the pattern is found, it looks up the issue <number> and closes the backport that has a milestone corresponding to the gradle.properties in the branch that is being pushed to.

Running the Application

The application is intended to be run as a GitHub Action. Here is an example workflow:

Note

The workflow should be present on every branch that you wish to be supported.

From GItHub’s Actions documentation:

Each workflow run will use the version of the workflow that is present in the associated commit SHA or Git ref of the event. This means that when a commit is pushed to these branches, it will not be processed by the backport bot because the workflow is not defined on those branches.

This can be a bit confusing when you see the branches element specify that it should operate only on branches that match *.x. However, it is important that the branches entry operates as a filter that further reduces the events that are operated on. It will not process an event that would not otherwise be processed (e.g. if the workflow does not exist on a branch that belongs to the event).

The usage of these types of filters is primarily meant to ensure that when you create new branches that you can prevent accidental invocation of workflows in branches without having to remember to remove the workflow in the branches. It also has the benefit of simplifying merging strategies for commits that involve the workflows.

backport-bot.yml

name: Backport Bot

on:
  issues:
    types: [labeled]
  pull_request:
    types: [labeled]
  push:
    branches:
      - '*.x'
jobs:
  build:
    permissions:
      contents: read
      issues: write
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'
      - name: Download BackportBot
        run: wget https://github.com/spring-io/backport-bot/releases/download/latest/backport-bot-0.0.1-SNAPSHOT.jar
      - name: Backport
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_EVENT: ${{ toJSON(github.event) }}
        run: java -jar backport-bot-0.0.1-SNAPSHOT.jar --github.accessToken="$GITHUB_TOKEN" --github.event_name "$GITHUB_EVENT_NAME" --github.event "$GITHUB_EVENT"

Add the Workflow to Every Branch