Backport action

.github/workflows/backports.yml

@@ -0,0 +1,73 @@
+name: Backport merged pull request
+on:
+  pull_request_target:
+    types: [closed]
+  issue_comment:
+    types: [created]
+permissions:
+  contents: write # so it can comment
+  pull-requests: write # so it can create pull requests
+jobs:
+  backport:
+    name: Backport pull request
+    runs-on: ubuntu-latest
+    # Only run when a pull request is merged
+    # or when a comment starting with `/backport` is created by a Tech Team member
+    if: |-
+      ${{
+        (
+          github.event_name == 'pull_request_target' &&
+          github.event.pull_request.merged
+        ) || (
+          github.event_name == 'issue_comment' &&
+          github.event.issue.pull_request &&
+          contains(fromJSON(vars.TECH_TEAM_USER_IDS), github.event.comment.user.id) &&
+          startsWith(github.event.comment.body, '/backport')
+        )
+      }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create backport pull requests
+        uses: korthout/backport-action@v2
+        with:
+          # Token to authenticate requests to GitHub. This is a Personal Access Token
+          # from the ckanbot user
+          github_token: ${{ secrets.BACKPORT_ACTION_PAT }}
+          # Run when there is one or more "Backport <branch>" labels,
+          # excluding "Backport pending"
+          label_pattern: "Backport (?!pending)([^ ]+)$"
+          merge_commits: skip
+          copy_assignees: true
+          pull_description: |-
+            This is an automated backport pull request 🏗️.
+
+            ### Details
+            |     |     |
+            | --- | --- |
+            | Original pull request | #${pull_number} (${pull_title}) |
+            | Original author | @${pull_author} |
+            | Target branch | **${target_branch}** |
+
+            Please make sure that all relevant checks pass before merging it.
+  backport-labels:
+    name: Backport failed labels
+    runs-on: ubuntu-latest
+    if: |-
+      ${{
+        github.event_name == 'issue_comment' &&
+        github.event.issue.pull_request &&
+        github.event.comment.user.id == vars.CKANBOT_USER_ID &&
+        startsWith(github.event.comment.body, 'Backport failed for')
+      }}
+    steps:
+      - name: Add Backport failed label to PR
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.BACKPORT_ACTION_PAT }}
+          script: |
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels: ["Backport failed"]
+            });

changes/8191.misc

@@ -0,0 +1 @@
+Add a GitHub for automated backports

doc/contributing/index.rst

@@ -41,3 +41,4 @@ of contributions to CKAN:
    database-migrations
    upgrading-dependencies
    release-process
+   maintenance-tools

doc/contributing/maintenance-tools.rst

@@ -0,0 +1,52 @@
+=================
+Maintenance tools
+=================
+
+This section describes tools and automations used by the development team to help
+in the maintenance of the CKAN source and repositories.
+
+.. _ckanbot:
+
+----------------------------
+The *ckanbot* GitHub account
+----------------------------
+
+For actions that need to be authenticated in the CKAN GitHub repository, we don't use
+personal accounts but rather a dedicated automated account, `@ckanbot <https://github.com/ckanbot>`_.
+
+This account has only write access to specific repositories needed, given via the `ckanbot team <https://github.com/orgs/ckan/teams/ckanbot/members>`_ of the *ckan* organization.
+
+
+.. _automated_backports:
+
+---------------------------
+Automated backports actions
+---------------------------
+
+.. note:: The backports action was added on April 2024
+
+To avoid havig to manually backport merged pull requests (PR) to release branches once these are merged,
+a new GitHub Action (`configuration file <https://github.com/ckan/ckan/blob/master/.github/workflows/backports.yml>`_)
+was added to automate this process whenever possible.
+
+The behaviour of this action is the following:
+
+* When a PR that has a label with the pattern ``Backport <branch>`` is merged,
+  it will trigger a backport action
+* If the PR commits merge cleanly into the target branch, a new PR will
+  be created against it, assigned to the same user as the merged one.
+  The usual checks will be run on the new PR
+* If the commits don't merge cleanly, a comment will be posted on the
+  orginal PR with the manual commands to fix the conflicts, and the PR
+  will be labelled with "Backport failed"
+* Additionally, Tech Team members can trigger a backport on open or
+  already closed PRs adding a comment starting with ``/backport`` (and
+  adding the relevant label)
+
+There are two repository variables and a repository secret needed to run the action
+(check the `documentation <https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository>`_
+on how to set up these):
+
+* The public variable ``TECH_TEAM_USER_IDS`` is a JSON list of the GitHub user ids of the Tech Team members. User ids can be found using the ``https://api.github.com/users/<user_name>`` endpoint.
+* The public variable ``CKANBOT_USER_ID`` is the user id of the :ref:`ckanbot`.
+* The secret ``BACKPORT_ACTION_PAT`` is a `Personal Access Token <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens>`_ of the ckanbot account, with enough permissions to write to the ckan/ckan repository.

doc/contributing/release-process.rst

@@ -475,12 +475,7 @@ Preparing patch releases
         git commit -am "Update version number"
         git push origin release-v2.5.2
 
-#. Cherry-pick PRs marked for back-port.
-
-   These are usually marked on Github using the ``Backport Pending`` `labels`_ and the
-   relevant labels for the versions they should be cherry-picked to (eg ``Backport 2.5.3``).
-   Remember to look for PRs that are closed i.e. merged. Remove the ``Backport Pending`` label once the
-   cherry-picking has been done (but leave the version ones).
+#. Backport PRs marked for backport using the :ref:`automated_backports` or manually if that fails.
 
 #. Ask the tech team if there are security fixes or other fixes to include.