release-pr.yml

name: Release PR

# Keeps one release pull request, chore: release <version>, open from release/next while CHANGELOG.md has entries
# under ## Unreleased. scripts/release_pr.py renames that section to the next +tibiash.N version and sets __version__
# to it. The tibia-sh App pushes the branch and opens the pull request, so the pull request's CI runs, which it would
# not for one opened with GITHUB_TOKEN, and turns on its auto-merge, so it merges itself once its required checks pass.
# drptbl can still merge it by hand. The tag job of that merge's run tags v<version> on the merge commit, provided the
# merge is exactly the release main before it proposes, and the tag starts release.yml.
on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions: {}

# Runs take turns, and a pending run is never replaced, so the run of every push to main, a release merge's included,
# runs to the end.
concurrency:
  group: release-pr
  cancel-in-progress: false
  queue: max

defaults:
  run:
    shell: bash

jobs:
  # Mints the App's token in the release-trigger environment, which deploys from main alone. The job installs
  # nothing, restores no cache and runs no dependency code: only git, gh and the standard-library
  # scripts/release_pr.py from its own checkout, under python3 -I. It commits only the two files the script wrote.
  propose:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment: release-trigger
    permissions:
      contents: read # the checkout and its tags
      pull-requests: read # the open release pull request
    steps:
      - name: Check out
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          fetch-tags: true
          persist-credentials: false
      # Exit 3 means CHANGELOG.md has no unreleased entries and nothing was written. The script checks that before it
      # works out a version, so a release merge's run, whose version is not tagged yet, ends here green.
      - name: Write the release
        id: propose
        run: |
          tags="$RUNNER_TEMP/tags.txt"
          git show-ref --tags --dereference > "$tags"
          if version="$(python3 -I scripts/release_pr.py propose --tags "$tags" --body "$RUNNER_TEMP/body.md")"; then
            if [[ ! $version =~ ^[0-9]+\.[0-9]+\.[0-9]+\+tibiash\.[0-9]+$ ]]; then
              echo "::error::release_pr.py propose printed a version that is not x.y.z+tibiash.N."
              exit 1
            fi
            echo "Proposing $version."
            echo "version=$version" >> "$GITHUB_OUTPUT"
          else
            status=$?
            if [ "$status" -ne 3 ]; then
              exit "$status"
            fi
            echo "CHANGELOG.md has no unreleased entries, so there is nothing to release."
          fi
      # With github.token. The App's login is its slug with [bot], as GitHub shows its pull requests.
      - name: Find the open release pull request
        id: pr
        env:
          GH_TOKEN: ${{ github.token }}
          GH_REPO: ${{ github.repository }}
          APP_LOGIN: ${{ vars.TIBIA_SH_APP_SLUG }}[bot]
        run: |
          if [[ ! $APP_LOGIN =~ ^[a-z0-9-]+\[bot\]$ ]]; then
            echo "::error::The App's login, from vars.TIBIA_SH_APP_SLUG, is not <slug>[bot]."
            exit 1
          fi
          query="head=$GITHUB_REPOSITORY_OWNER:release/next&base=main&state=open"
          number="$(timeout --kill-after=10 120 gh api "repos/{owner}/{repo}/pulls?$query" \
            --jq 'map(select(.user.login == env.APP_LOGIN)) | .[0].number // empty')"
          if [[ ! $number =~ ^[0-9]*$ ]]; then
            echo "::error::The open release pull request has no plain number."
            exit 1
          fi
          echo "number=$number" >> "$GITHUB_OUTPUT"
      # A token of the App for this repository alone, which expires within the hour: pull requests, to close the one
      # that has nothing left to release.
      - id: close_token
        if: ${{ steps.propose.outputs.version == '' && steps.pr.outputs.number != '' }}
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          client-id: ${{ vars.TIBIA_SH_APP_CLIENT_ID }}
          private-key: ${{ secrets.TIBIA_SH_APP_PRIVATE_KEY }}
          owner: tibia-sh
          repositories: tibiawiki-sql
          permission-pull-requests: write
      - name: Close the release pull request
        if: ${{ steps.propose.outputs.version == '' && steps.pr.outputs.number != '' }}
        env:
          GH_TOKEN: ${{ steps.close_token.outputs.token }}
          GH_REPO: ${{ github.repository }}
          PR: ${{ steps.pr.outputs.number }}
        run: |
          timeout --kill-after=10 120 gh pr close "$PR" \
            --comment "CHANGELOG.md on main has no unreleased entries, so there is nothing to release."
      - name: Commit the release
        if: ${{ steps.propose.outputs.version != '' }}
        env:
          VERSION: ${{ steps.propose.outputs.version }}
          GIT_AUTHOR_NAME: github-actions[bot]
          GIT_AUTHOR_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
          GIT_COMMITTER_NAME: github-actions[bot]
          GIT_COMMITTER_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
        run: |
          if [[ "$(git status --porcelain)" != $' M CHANGELOG.md\n M tibiawikisql/__init__.py' ]]; then
            echo "::error::propose must change CHANGELOG.md and tibiawikisql/__init__.py, and nothing else."
            exit 1
          fi
          git add CHANGELOG.md tibiawikisql/__init__.py
          git commit --quiet -m "chore: release $VERSION"
      # A token of the App for this repository alone, which expires within the hour: contents, to push release/next,
      # and pull requests, to open or update its pull request. Minted after the release is committed, so nothing
      # before this step runs with it.
      - id: push_token
        if: ${{ steps.propose.outputs.version != '' }}
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          client-id: ${{ vars.TIBIA_SH_APP_CLIENT_ID }}
          private-key: ${{ secrets.TIBIA_SH_APP_PRIVATE_KEY }}
          owner: tibia-sh
          repositories: tibiawiki-sql
          permission-contents: write
          permission-pull-requests: write
      # Force-pushes release/next, which replaces the previous proposal, then opens the pull request or updates the open
      # one, and hands its number on. The token reaches git through a credential helper that reads it from the
      # environment, so it is never written to .git/config and never appears on a command line.
      - name: Push release/next and open or update its pull request
        id: push
        if: ${{ steps.propose.outputs.version != '' }}
        env:
          GH_TOKEN: ${{ steps.push_token.outputs.token }}
          GH_REPO: ${{ github.repository }}
          VERSION: ${{ steps.propose.outputs.version }}
          PR: ${{ steps.pr.outputs.number }}
        run: |
          title="chore: release $VERSION"
          # shellcheck disable=SC2016 # git's shell expands $GH_TOKEN when it runs the helper
          timeout --kill-after=10 120 git -c credential.helper= \
            -c 'credential.helper=!f() { echo username=x-access-token; echo "password=$GH_TOKEN"; }; f' \
            push --force origin HEAD:refs/heads/release/next
          if [[ -n $PR ]]; then
            timeout --kill-after=10 120 gh api --method PATCH "repos/{owner}/{repo}/pulls/$PR" --silent \
              -f title="$title" -F body=@"$RUNNER_TEMP/body.md"
            number="$PR"
          else
            number="$(timeout --kill-after=10 120 gh api "repos/{owner}/{repo}/pulls" --jq .number \
              -f head=release/next -f base=main -f title="$title" -F body=@"$RUNNER_TEMP/body.md")"
          fi
          echo "number=$number" >> "$GITHUB_OUTPUT"
      # GitHub merges the release pull request once its required checks pass, with a merge commit, the one merge method
      # this repository allows, and records the App, which turned auto-merge on, as the merger. A step output is data,
      # so only a number whose text is digits alone reaches gh. Auto-merge is turned on only when it is off, which it
      # is for a new pull request, or when GitHub turned it off.
      - name: Turn on auto-merge for the release pull request
        if: ${{ steps.propose.outputs.version != '' }}
        env:
          GH_TOKEN: ${{ steps.push_token.outputs.token }}
          GH_REPO: ${{ github.repository }}
          PR: ${{ steps.push.outputs.number }}
        run: |
          if [[ ! $PR =~ ^[0-9]+$ ]]; then
            echo "::error::The release pull request has no plain number, so its auto-merge was not turned on."
            exit 1
          fi
          auto_merge="$(timeout --kill-after=10 120 gh api "repos/{owner}/{repo}/pulls/$PR" --jq .auto_merge)"
          if [[ -z $auto_merge ]]; then
            timeout --kill-after=10 120 gh pr merge "$PR" --auto --merge
          else
            echo "Auto-merge is already on for pull request $PR."
          fi

  # Tags the release that the merge of the release pull request made. The list of a commit's pull requests has no
  # merged_by, so the job reads, with github.token, the pull request whose merge commit is the pushed commit on its
  # own, and scripts/release_pr.py decides from it. Only the App's release/next pull request, merged by the App's
  # auto-merge or by drptbl, tags v<version> at the merge commit, and only when the merge is exactly the release that
  # main before it proposes: generator code comes through ordinary pull requests, never the release one. The
  # same isolation as the propose job, and the App's token, which the release tags ruleset lets create v* tags, is
  # minted only to create the tag. The tag's push starts release.yml.
  tag:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment: release-trigger
    permissions:
      contents: read # the checkout and its tags
      pull-requests: read # the pull request the pushed commit merged
    steps:
      - name: Check out
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          fetch-tags: true
          persist-credentials: false
      # With no merged pull request, as for a direct push, the script is given null. It fails when the version is
      # untagged, and skips otherwise.
      - name: Read the merged pull request
        env:
          GH_TOKEN: ${{ github.token }}
          GH_REPO: ${{ github.repository }}
        run: |
          numbers="$(timeout --kill-after=10 120 gh api "repos/{owner}/{repo}/commits/$GITHUB_SHA/pulls" \
            --jq '[.[] | select(.merge_commit_sha == env.GITHUB_SHA and .merged_at) | "\(.number)"] | join(" ")')"
          if [[ -z $numbers ]]; then
            echo null > "$RUNNER_TEMP/pr.json"
          elif [[ $numbers =~ ^[0-9]+$ ]]; then
            timeout --kill-after=10 120 gh api "repos/{owner}/{repo}/pulls/$numbers" > "$RUNNER_TEMP/pr.json"
          else
            echo "::error::More than one merged pull request has $GITHUB_SHA as its merge commit."
            exit 1
          fi
      # The checkout has the whole history, so the pushed commit's first parent, main before the push, is there. The
      # decision runs that parent's scripts/release_pr.py from a worktree of the parent, so a release pull request
      # cannot rewrite the rules that tag it. The script recomputes the release from the parent's CHANGELOG.md and
      # tibiawikisql/__init__.py, as propose writes it, and fail turns the run red with its reason: the merge is not
      # exactly that release, or the version has no tag and no merged pull request was found, as for a release merge
      # GitHub did not list yet.
      - name: Decide
        id: decide
        env:
          APP_LOGIN: ${{ vars.TIBIA_SH_APP_SLUG }}[bot]
        run: |
          tags="$RUNNER_TEMP/tags.txt"
          changed="$RUNNER_TEMP/changed.txt"
          main="$RUNNER_TEMP/main"
          git show-ref --tags --dereference > "$tags"
          git diff --name-only HEAD^1 HEAD > "$changed"
          git worktree add --quiet --detach "$main" HEAD^1
          result="$(python3 -I "$main/scripts/release_pr.py" tag-decision --tags "$tags" --pr "$RUNNER_TEMP/pr.json" \
            --head "$GITHUB_SHA" --app-login "$APP_LOGIN" --changed-files "$changed" --base "$main")"
          decision="$(sed -n 's/^decision=//p' <<< "$result")"
          version="$(sed -n 's/^version=//p' <<< "$result")"
          reason="$(sed -n 's/^reason=//p' <<< "$result")"
          case $decision in
            tag) echo "Tagging v$version at $GITHUB_SHA." ;;
            noop) echo "v$version already points at $GITHUB_SHA." ;;
            skip) echo "$GITHUB_SHA is not a release merge by the App or drptbl, so nothing is tagged." ;;
            fail)
              echo "::error::v$version cannot be tagged at $GITHUB_SHA: $reason"
              exit 1
              ;;
            *)
              echo "::error::release_pr.py tag-decision printed an unknown decision."
              exit 1
              ;;
          esac
          echo "decision=$decision" >> "$GITHUB_OUTPUT"
          echo "version=$version" >> "$GITHUB_OUTPUT"
      # A token of the App for this repository alone, which expires within the hour: contents, to create the tag.
      - id: tag_token
        if: ${{ steps.decide.outputs.decision == 'tag' }}
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          client-id: ${{ vars.TIBIA_SH_APP_CLIENT_ID }}
          private-key: ${{ secrets.TIBIA_SH_APP_PRIVATE_KEY }}
          owner: tibia-sh
          repositories: tibiawiki-sql
          permission-contents: write
      - name: Create the tag
        if: ${{ steps.decide.outputs.decision == 'tag' }}
        env:
          GH_TOKEN: ${{ steps.tag_token.outputs.token }}
          GH_REPO: ${{ github.repository }}
          VERSION: ${{ steps.decide.outputs.version }}
        run: |
          if [[ ! $VERSION =~ ^[0-9]+\.[0-9]+\.[0-9]+\+tibiash\.[0-9]+$ || ! $GITHUB_SHA =~ ^[0-9a-f]{40}$ ]]; then
            echo "::error::The version is not x.y.z+tibiash.N, or the pushed commit is not a full SHA."
            exit 1
          fi
          timeout --kill-after=10 120 gh api "repos/{owner}/{repo}/git/refs" --silent \
            -f ref="refs/tags/v$VERSION" -f sha="$GITHUB_SHA"
          echo "Tagged v$VERSION at $GITHUB_SHA."