ci-cd.yml

---

name: 🧪

on:
  merge_group:
  push:  # publishes to TestPyPI pushes to the main branch
    branches-ignore:
    - dependabot/**  # Dependabot always creates PRs
    - gh-readonly-queue/**  # Temporary merge queue-related GH-made branches
    - maintenance/pip-tools-constraint-lockfiles  # Lock files through PRs
    - maintenance/pip-tools-constraint-lockfiles-**  # Lock files through PRs
    - patchback/backports/**  # Patchback always creates PRs
    - pre-commit-ci-update-config  # pre-commit.ci always creates a PR
  pull_request:
    types:
    - opened  # default
    - synchronize  # default
    - reopened  # default
    - ready_for_review  # used in PRs created from the release workflow
  schedule:
  - cron: 1 0 * * *  # Run daily at 0:01 UTC
  workflow_dispatch:
    inputs:
      release-version:
        # github.event_name == 'workflow_dispatch'
        # && github.event.inputs.release-version
        description: >-
          Target PEP440-compliant version to release.
          Please, don't prepend `v`.
        required: true
        type: string
      release-committish:
        # github.event_name == 'workflow_dispatch'
        # && github.event.inputs.release-committish
        default: ''
        description: >-
          The commit to be released to PyPI and tagged
          in Git as `release-version`. Normally, you
          should keep this empty.
        type: string
      YOLO:
        default: false
        description: >-
          Set this flag to disregard the outcome of the
          test stage. The test results will block the
          release otherwise. Only use this under
          extraordinary circumstances to ignore the test
          failures and cut the release regardless.
        type: boolean

concurrency:
  group: >-
    ${{
        github.workflow
    }}-${{
        github.ref_type
    }}-${{
        github.event.pull_request.number || github.sha
    }}
  cancel-in-progress: true

env:
  FORCE_COLOR: 1  # Request colored output from CLI tools supporting it
  MYPY_FORCE_COLOR: 1  # MyPy's color enforcement
  PIP_DISABLE_PIP_VERSION_CHECK: 1  # Hide "there's a newer pip" message
  PIP_NO_PYTHON_VERSION_WARNING: 1  # Hide "this Python is deprecated" message
  PIP_NO_WARN_SCRIPT_LOCATION: 1  # Hide "script dir is not in $PATH" message
  PRE_COMMIT_COLOR: always
  PROJECT_NAME: octomachinery
  PY_COLORS: 1  # Recognized by the `py` package, dependency of `pytest`
  PYTHONIOENCODING: utf-8
  PYTHONUTF8: 1
  TOX_PARALLEL_NO_SPINNER: 1  # Disable tox's parallel run spinner animation
  TOX_TESTENV_PASSENV: >-  # Make tox-wrapped tools see color requests
    FORCE_COLOR
    MYPY_FORCE_COLOR
    NO_COLOR
    PIP_DISABLE_PIP_VERSION_CHECK
    PIP_NO_PYTHON_VERSION_WARNING
    PIP_NO_WARN_SCRIPT_LOCATION
    PRE_COMMIT_COLOR
    PY_COLORS
    PYTEST_THEME
    PYTEST_THEME_MODE
    PYTHONIOENCODING
    PYTHONLEGACYWINDOWSSTDIO
    PYTHONUTF8
  UPSTREAM_REPOSITORY_ID: >-
    164512032

run-name: >-
  ${{
    github.event_name == 'workflow_dispatch'
    && format('📦 Releasing v{0}...', github.event.inputs.release-version)
    || ''
  }}
  ${{
      github.event.pull_request.number && 'PR' || ''
  }}${{
      !github.event.pull_request.number && 'Commit' || ''
  }}
  ${{ github.event.pull_request.number || github.sha }}
  triggered by: ${{ github.event_name }} of ${{
    github.ref
  }} ${{
    github.ref_type
  }}
  (workflow run ID: ${{
    github.run_id
  }}; number: ${{
    github.run_number
  }}; attempt: ${{
    github.run_attempt
  }})

jobs:
  pre-setup:
    name: ⚙️ Pre-set global build settings

    runs-on: ubuntu-latest

    timeout-minutes: 1

    defaults:
      run:
        shell: python
    outputs:
      # NOTE: These aren't env vars because the `${{ env }}` context is
      # NOTE: inaccessible when passing inputs to reusable workflows.
      dists-artifact-name: python-package-distributions
      dist-version: >-
        ${{
            steps.request-check.outputs.release-requested == 'true'
            && github.event.inputs.release-version
            || steps.scm-version.outputs.dist-version
        }}
      is-untagged-devel: >-
        ${{ steps.untagged-check.outputs.is-untagged-devel || false }}
      release-requested: >-
        ${{
            steps.request-check.outputs.release-requested || false
        }}
      is-yolo-mode: >-
        ${{
          (
            steps.request-check.outputs.release-requested == 'true'
            && github.event.inputs.YOLO
          )
          && true || false
        }}
      cache-key-files: >-
        ${{ steps.calc-cache-key-files.outputs.files-hash-key }}
      git-tag: ${{ steps.git-tag.outputs.tag }}
      sdist-artifact-name: ${{ steps.artifact-name.outputs.sdist }}
      wheel-artifact-name: ${{ steps.artifact-name.outputs.wheel }}
      upstream-repository-id: ${{ env.UPSTREAM_REPOSITORY_ID }}
    steps:
    - name: Switch to using Python v3.11 by default
      uses: actions/setup-python@v5
      with:
        python-version: 3.11
    - name: >-
        Mark the build as untagged '${{
            github.event.repository.default_branch
        }}' branch build
      id: untagged-check
      if: >-
        github.event_name == 'push' &&
        github.ref == format(
          'refs/heads/{0}', github.event.repository.default_branch
        )
      run: |
        from os import environ
        from pathlib import Path

        FILE_APPEND_MODE = 'a'

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print('is-untagged-devel=true', file=outputs_file)
    - name: Mark the build as "release request"
      id: request-check
      if: github.event_name == 'workflow_dispatch'
      run: |
        from os import environ
        from pathlib import Path

        FILE_APPEND_MODE = 'a'

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print('release-requested=true', file=outputs_file)
    - name: Check out src from Git
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      uses: actions/checkout@v4
      with:
        fetch-depth: >-
          ${{
            steps.request-check.outputs.release-requested == 'true'
            && 1 || 0
          }}
        ref: ${{ github.event.inputs.release-committish }}
    - name: >-
        Calculate Python interpreter version hash value
        for use in the cache key
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      id: calc-cache-key-py
      run: |
        from hashlib import sha512
        from os import environ
        from pathlib import Path
        from sys import version

        FILE_APPEND_MODE = 'a'

        hash = sha512(version.encode()).hexdigest()

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(f'py-hash-key={hash}', file=outputs_file)
    - name: >-
        Calculate dependency files' combined hash value
        for use in the cache key
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      id: calc-cache-key-files
      run: |
        from os import environ
        from pathlib import Path

        FILE_APPEND_MODE = 'a'

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(
                "files-hash-key=${{
                    hashFiles(
                      'setup.cfg', 'setup.py', 'tox.ini', 'pyproject.toml',
                      '.pre-commit-config.yaml', 'pytest.ini'
                    )
                }}",
                file=outputs_file,
            )
    - name: Get pip cache dir
      id: pip-cache-dir
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      run: >-
        echo "dir=$(python -m pip cache dir)" >> "${GITHUB_OUTPUT}"
      shell: bash
    - name: Set up pip cache
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      uses: actions/cache@v4
      with:
        path: ${{ steps.pip-cache-dir.outputs.dir }}
        key: >-
          ${{ runner.os }}-pip-${{
          steps.calc-cache-key-py.outputs.py-hash-key }}-${{
          steps.calc-cache-key-files.outputs.files-hash-key }}
        restore-keys: |
          ${{ runner.os }}-pip-${{
              steps.calc-cache-key-py.outputs.py-hash-key
          }}-
          ${{ runner.os }}-pip-
          ${{ runner.os }}-
    - name: Drop Git tags from HEAD for non-release requests
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      run: >-
        git tag --points-at HEAD
        |
        xargs git tag --delete
      shell: bash
    - name: Set up versioning prerequisites
      if: >-
        steps.request-check.outputs.release-requested != 'true'
      run: >-
        python -m
        pip install
        --user
        setuptools-scm
      shell: bash
    - name: Set the current dist version from Git
      if: steps.request-check.outputs.release-requested != 'true'
      id: scm-version
      run: |
        from os import environ
        from pathlib import Path

        import setuptools_scm

        FILE_APPEND_MODE = 'a'

        ver = setuptools_scm.get_version(
          ${{
              steps.untagged-check.outputs.is-untagged-devel == 'true'
              && 'local_scheme="no-local-version"' || ''
          }}
        )
        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(f'dist-version={ver}', file=outputs_file)
    - name: Set the target Git tag
      id: git-tag
      run: |
        from os import environ
        from pathlib import Path

        FILE_APPEND_MODE = 'a'

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(
                "tag=v${{
                    steps.request-check.outputs.release-requested == 'true'
                    && github.event.inputs.release-version
                    || steps.scm-version.outputs.dist-version
                }}",
                file=outputs_file,
            )
    - name: Set the expected dist artifact names
      id: artifact-name
      run: |
        from os import environ
        from pathlib import Path

        FILE_APPEND_MODE = 'a'

        dist_file_prj_base_name = '${{ env.PROJECT_NAME }}'.replace('-', '_')
        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(
                f"sdist={dist_file_prj_base_name !s}-${{
                    steps.request-check.outputs.release-requested == 'true'
                    && github.event.inputs.release-version
                    || steps.scm-version.outputs.dist-version
                }}.tar.gz",
                file=outputs_file,
            )
            print(
                f"wheel={dist_file_prj_base_name !s}-${{
                    steps.request-check.outputs.release-requested == 'true'
                    && github.event.inputs.release-version
                    || steps.scm-version.outputs.dist-version
                }}-py3-none-any.whl",
                file=outputs_file,
            )

  build:
    name: >-
      📦 ${{ needs.pre-setup.outputs.git-tag }}
      [mode: ${{
        fromJSON(needs.pre-setup.outputs.is-untagged-devel)
        && 'test' || ''
      }}${{
        fromJSON(needs.pre-setup.outputs.release-requested)
        && 'release' || ''
      }}${{
        (
          !fromJSON(needs.pre-setup.outputs.is-untagged-devel)
          && !fromJSON(needs.pre-setup.outputs.release-requested)
        ) && 'nightly' || ''
      }}]
    needs:
    - pre-setup

    runs-on: ubuntu-latest

    timeout-minutes: 1

    env:
      TOXENV: build-dists

    steps:
    - name: Switch to using Python v3.11
      uses: actions/setup-python@v5
      with:
        python-version: 3.11

    - name: Grab the source from Git
      uses: actions/checkout@v4
      with:
        fetch-depth: >-
          ${{
              fromJSON(needs.pre-setup.outputs.release-requested)
              && 1 || 0
          }}
        ref: ${{ github.event.inputs.release-committish }}

    - name: >-
        Calculate Python interpreter version hash value
        for use in the cache key
      id: calc-cache-key-py
      run: |
        from hashlib import sha512
        from os import environ
        from pathlib import Path
        from sys import version

        FILE_APPEND_MODE = 'a'

        hash = sha512(version.encode()).hexdigest()

        with Path(environ['GITHUB_OUTPUT']).open(
                mode=FILE_APPEND_MODE,
        ) as outputs_file:
            print(f'py-hash-key={hash}', file=outputs_file)
      shell: python
    - name: Get pip cache dir
      id: pip-cache-dir
      run: >-
        echo "dir=$(python -m pip cache dir)" >> "${GITHUB_OUTPUT}"
    - name: Set up pip cache
      uses: actions/cache@v4
      with:
        path: ${{ steps.pip-cache-dir.outputs.dir }}
        key: >-
          ${{ runner.os }}-pip-${{
          steps.calc-cache-key-py.outputs.py-hash-key }}-${{
          needs.pre-setup.outputs.cache-key-files }}
        restore-keys: |
          ${{ runner.os }}-pip-${{
              steps.calc-cache-key-py.outputs.py-hash-key
          }}-
          ${{ runner.os }}-pip-
    - name: Install tox
      run: >-
        python -m
        pip install
        --user
        tox

    - name: Pre-populate the tox env
      run: >-
        python -m
        tox
        --parallel auto
        --parallel-live
        --skip-missing-interpreters false
        --notest

    - name: Drop Git tags from HEAD for non-tag-create events
      if: >-
        !fromJSON(needs.pre-setup.outputs.release-requested)
      run: >-
        git tag --points-at HEAD
        |
        xargs git tag --delete
      shell: bash

    - name: Setup git user as [bot]
      if: >-
        fromJSON(needs.pre-setup.outputs.release-requested)
        || fromJSON(needs.pre-setup.outputs.is-untagged-devel)
      uses: fregante/setup-git-user@v2
    - name: >-
        Tag the release in the local Git repo
        as ${{ needs.pre-setup.outputs.git-tag }}
        for setuptools-scm to set the desired version
      if: >-
        fromJSON(needs.pre-setup.outputs.release-requested)
      run: >-
        git tag
        -m '${{ needs.pre-setup.outputs.git-tag }}'
        '${{ needs.pre-setup.outputs.git-tag }}'
        --
        ${{
          fromJSON(needs.pre-setup.outputs.release-requested)
          && github.event.inputs.release-committish || ''
        }}

    - name: Install tomlkit Python distribution package
      if: >-
        fromJSON(needs.pre-setup.outputs.is-untagged-devel)
      run: >-
        python -m pip install --user tomlkit
    - name: Instruct setuptools-scm not to add a local version part
      if: >-
        fromJSON(needs.pre-setup.outputs.is-untagged-devel)
      run: |
        from pathlib import Path

        import tomlkit

        pyproject_toml_path = Path.cwd() / 'pyproject.toml'
        pyproject_toml_txt = pyproject_toml_path.read_text()
        pyproject_toml = tomlkit.loads(pyproject_toml_txt)
        setuptools_scm_section = pyproject_toml['tool']['setuptools_scm']
        setuptools_scm_section['local_scheme'] = 'no-local-version'
        patched_pyproject_toml_txt = tomlkit.dumps(pyproject_toml)
        pyproject_toml_path.write_text(patched_pyproject_toml_txt)
      shell: python
    - name: Pretend that pyproject.toml is unchanged
      if: >-
        fromJSON(needs.pre-setup.outputs.is-untagged-devel)
      run: |
        git diff --color=always
        git update-index --assume-unchanged pyproject.toml

    - name: Build dists
      run: >-
        python -m
        tox
        --parallel auto
        --parallel-live
        --skip-missing-interpreters false
        --skip-pkg-install
    - name: Verify that the artifacts with expected names got created
      run: >-
        ls -1
        'dist/${{ needs.pre-setup.outputs.sdist-artifact-name }}'
        'dist/${{ needs.pre-setup.outputs.wheel-artifact-name }}'
    - name: Store the distribution packages
      uses: actions/upload-artifact@v4
      with:
        name: >-
          ${{ needs.pre-setup.outputs.dists-artifact-name }}
        # NOTE: Exact expected file names are specified here
        # NOTE: as a safety measure — if anything weird ends
        # NOTE: up being in this dir or not all dists will be
        # NOTE: produced, this will fail the workflow.
        path: |
          dist/${{ needs.pre-setup.outputs.sdist-artifact-name }}
          dist/${{ needs.pre-setup.outputs.wheel-artifact-name }}
        retention-days: >-
          ${{
              (
                fromJSON(needs.pre-setup.outputs.release-requested)
              ) && 90 || 30
          }}

  tests:
    name: >-
      ${{
        (matrix.toxenv == 'py' || matrix.toxenv == 'old-deps')
        && 'py' || ''
      }}${{
        (matrix.toxenv == 'py' || matrix.toxenv == 'old-deps')
        && matrix.python-version || matrix.toxenv
      }}
      ${{ matrix.toxenv == 'old-deps' && '|' || '' }}
      ${{ matrix.toxenv == 'old-deps' && matrix.toxenv || '' }}
      |
      ${{
        (matrix.toxenv == 'py' || matrix.toxenv == 'old-deps')
        && matrix.runner-vm-os || 'tox'
      }}
    needs:
    - build
    - pre-setup  # transitive, for accessing settings

    runs-on: ${{ matrix.runner-vm-os }}

    timeout-minutes: 2

    strategy:
      fail-fast: true
      matrix:
        python-version:
        # NOTE: The latest and the lowest supported Pythons are prioritized
        # NOTE: to improve the responsiveness. It's nice to see the most
        # NOTE: important results first.
        - ~3.13.0-0
        - 3.7
        - 3.12
        - 3.11
        - >-
          3.10
        - 3.9
        - 3.8
        runner-vm-os:
        - ubuntu-24.04
        - ubuntu-22.04
        - macos-14  # ARM64
        - macos-13  # Intel
        toxenv:
        - py
        - old-deps
        include:
        - runner-vm-os: ubuntu-latest
          python-version: 3.9
          toxenv: pre-commit
        - runner-vm-os: ubuntu-latest
          python-version: 3.9
          toxenv: check-docs
        - runner-vm-os: ubuntu-latest
          python-version: 3.9
          toxenv: build-docs
        - runner-vm-os: ubuntu-latest
          python-version: 3.9
          toxenv: build-dists
        exclude:
        - runner-vm-os: macos-14
          python-version: 3.7
        - runner-vm-os: ubuntu-20.04
          python-version: 3.7

    continue-on-error: >-
      ${{
          (
            fromJSON(needs.pre-setup.outputs.is-yolo-mode) ||
            (
              startsWith(matrix.python-version, '~')
            ) ||
            contains(matrix.python-version, 'alpha')
          ) && true || false
      }}

    env:
      TOXENV: ${{ matrix.toxenv }}

    steps:
    - name: Grab the source from Git
      uses: actions/checkout@v4
      with:
        ref: ${{ github.event.inputs.release-committish }}

    - name: Download all the dists
      uses: actions/download-artifact@v4
      with:
        name: >-
          ${{ needs.pre-setup.outputs.dists-artifact-name }}
        path: dist/

    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.python-version }}
    - name: Pip cache
      uses: actions/cache@v4
      with:
        path: >-
          ${{
            runner.os == 'Linux' &&
            '~/.cache/pip'
            || ''
          }}${{
            runner.os == 'macOS' &&
            '~/Library/Caches/pip'
            || ''
          }}${{
            runner.os == 'Windows' &&
            '~\AppData\Local\pip\Cache'
            || ''
          }}
        key: >-
          ${{ runner.os }}-pip-${{ hashFiles('setup.cfg') }}-${{
          hashFiles('tox.ini') }}-${{
          hashFiles('pyproject.toml') }}-${{
          hashFiles('.pre-commit-config.yaml') }}-${{
          hashFiles('pytest.ini') }}
        restore-keys: |
          ${{ runner.os }}-pip-
          ${{ runner.os }}-
    - name: Install tox
      run: >-
        python -m
        pip install
        --upgrade
        tox
    - name: 'Initialize tox envs: ${{ matrix.toxenv }}'
      run: >-
        python -m
        tox
        --parallel auto
        --parallel-live
        -vv
        --skip-missing-interpreters false
        --installpkg 'dist/${{ needs.pre-setup.outputs.wheel-artifact-name }}'
        --notest
    - name: Initialize pre-commit envs if needed
      run: >-
        test -d .tox/pre-commit
        && .tox/pre-commit/bin/python -m pre_commit install-hooks
        || :
    - name: Test with tox
      run: >-
        python -m
        tox
        --parallel auto
        --parallel-live
        --installpkg 'dist/${{ needs.pre-setup.outputs.wheel-artifact-name }}'
        -vv

  check:  # This job does nothing and is only used for the branch protection
    if: always()

    needs:
    - pre-setup  # transitive, for accessing settings
    - tests

    runs-on: ubuntu-latest

    timeout-minutes: 1

    steps:
    - name: Decide whether the needed jobs succeeded or failed
      uses: re-actors/alls-green@release/v1
      with:
        allowed-failures: >-
          ${{
            fromJSON(needs.pre-setup.outputs.is-yolo-mode)
            && 'tests'
            || ''
          }}
        jobs: ${{ toJSON(needs) }}

  publish-pypi:
    name: Publish 🐍📦 ${{ needs.pre-setup.outputs.git-tag }} to PyPI
    needs:
    - check
    - pre-setup  # transitive, for accessing settings
    if: >-
      always()
      && needs.check.result == 'success'
      && fromJSON(needs.pre-setup.outputs.release-requested)
      && needs.pre-setup.outputs.upstream-repository-id == github.repository_id

    runs-on: ubuntu-latest

    timeout-minutes: 1

    environment:
      name: pypi
      url: >-
        https://pypi.org/project/${{ env.PROJECT_NAME }}/${{
          needs.pre-setup.outputs.dist-version
        }}

    permissions:
      contents: read  # This job doesn't need to `git push` anything
      id-token: write  # PyPI Trusted Publishing (OIDC)

    steps:
    - name: Download all the dists
      uses: actions/download-artifact@v4
      with:
        name: >-
          ${{ needs.pre-setup.outputs.dists-artifact-name }}
        path: dist/
    - name: >-
        Publish 🐍📦 ${{ needs.pre-setup.outputs.git-tag }} to PyPI
      uses: pypa/gh-action-pypi-publish@release/v1

  publish-testpypi:
    name: Publish 🐍📦 ${{ needs.pre-setup.outputs.git-tag }} to TestPyPI
    needs:
    - check
    - pre-setup  # transitive, for accessing settings
    if: >-
      always()
      && needs.check.result == 'success'
      && (
        fromJSON(needs.pre-setup.outputs.is-untagged-devel)
        || fromJSON(needs.pre-setup.outputs.release-requested)
      )
      && needs.pre-setup.outputs.upstream-repository-id == github.repository_id

    runs-on: ubuntu-latest

    timeout-minutes: 1

    environment:
      name: testpypi
      url: >-
        https://test.pypi.org/project/${{ env.PROJECT_NAME }}/${{
          needs.pre-setup.outputs.dist-version
        }}

    permissions:
      contents: read  # This job doesn't need to `git push` anything
      id-token: write  # PyPI Trusted Publishing (OIDC)

    steps:
    - name: Download all the dists
      uses: actions/download-artifact@v4
      with:
        name: >-
          ${{ needs.pre-setup.outputs.dists-artifact-name }}
        path: dist/
    - name: >-
        Publish 🐍📦 ${{ needs.pre-setup.outputs.git-tag }} to TestPyPI
      uses: pypa/gh-action-pypi-publish@release/v1
      with:
        repository-url: https://test.pypi.org/legacy/

  post-release-repo-update:
    name: >-
      Publish post-release Git tag
      for ${{ needs.pre-setup.outputs.git-tag }}
    needs:
    - publish-pypi
    - pre-setup  # transitive, for accessing settings

    runs-on: ubuntu-latest

    timeout-minutes: 1

    steps:
    - name: >-
        Check if the requested tag ${{ needs.pre-setup.outputs.git-tag }}
        is present and is pointing at the required commit ${{
          github.event.inputs.release-committish
        }}
      id: existing-remote-tag-check
      run: |
        REMOTE_TAGGED_COMMIT_SHA="$(
          git ls-remote --tags --refs $(git remote get-url origin) '${{
            needs.pre-setup.outputs.git-tag
          }}' | awk '{print $1}'
        )"

        if [[ "${REMOTE_TAGGED_COMMIT_SHA}" == '${{
          github.event.inputs.release-committish
        }}' ]]
        then
          echo "already-exists=true" >> "${GITHUB_OUTPUT}"
        fi

    - name: Fetch the src snapshot
      if: steps.existing-remote-tag-check.outputs.already-exists == 'true'
      uses: actions/checkout@v4
      with:
        fetch-depth: 1
        ref: ${{ github.event.inputs.release-committish }}
    - name: Setup git user as [bot]
      if: steps.existing-remote-tag-check.outputs.already-exists == 'true'
      uses: fregante/setup-git-user@v1.1.0
    - name: >-
        Tag the release in the local Git repo
        as ${{ needs.pre-setup.outputs.git-tag }}
      if: steps.existing-remote-tag-check.outputs.already-exists == 'true'
      run: >-
        git tag
        -m '${{ needs.pre-setup.outputs.git-tag }}'
        -m 'Published at https://pypi.org/project/${{ env.PROJECT_NAME }}/${{
          needs.pre-setup.outputs.dist-version
        }}'
        -m 'This release has been produced by the following workflow run: ${{
          github.server_url
        }}/${{
          github.repository
        }}/actions/runs/${{
          github.run_id
        }}'
        '${{ needs.pre-setup.outputs.git-tag }}'
        --
        ${{ github.event.inputs.release-committish }}
    - name: >-
        Push ${{ needs.pre-setup.outputs.git-tag }} tag corresponding
        to the just published release back to GitHub
      if: steps.existing-remote-tag-check.outputs.already-exists == 'true'
      run: >-
        git push --atomic origin '${{ needs.pre-setup.outputs.git-tag }}'

  publish-github-release:
    name: >-
      Publish a GitHub Release for
      ${{ needs.pre-setup.outputs.git-tag }}
    needs:
    - post-release-repo-update
    - pre-setup  # transitive, for accessing settings
    if: >-
      always()
      && needs.post-release-repo-update.result == 'success'

    runs-on: ubuntu-latest

    timeout-minutes: 1

    permissions:
      contents: write
      discussions: write

    steps:
    - name: Download all the dists
      uses: actions/download-artifact@v4
      with:
        name: >-
          ${{ needs.pre-setup.outputs.dists-artifact-name }}
        path: dist/

    - name: >-
        Publish a GitHub Release for
        ${{ needs.pre-setup.outputs.git-tag }}
      uses: ncipollo/release-action@v1
      with:
        allowUpdates: false
        artifactErrorsFailBuild: false
        artifacts: |
          dist/${{ needs.pre-setup.outputs.sdist-artifact-name }}
          dist/${{ needs.pre-setup.outputs.wheel-artifact-name }}
        artifactContentType: raw  # Because whl and tgz are of different types
        body: >
          # Release ${{ needs.pre-setup.outputs.git-tag }}


          This release is published to
          https://pypi.org/project/${{ env.PROJECT_NAME }}/${{
            needs.pre-setup.outputs.dist-version
          }}.


          This release has been produced by the following workflow run: ${{
            github.server_url
          }}/${{
            github.repository
          }}/actions/runs/${{
            github.run_id
          }}.
        # bodyFile:  # FIXME: Use once Towncrier is integrated.
        commit: ${{ github.event.inputs.release-committish }}
        discussionCategory: Announcements
        draft: false
        name: ${{ needs.pre-setup.outputs.git-tag }}
        # omitBody: false
        omitBodyDuringUpdate: true
        omitName: false
        omitNameDuringUpdate: true
        omitPrereleaseDuringUpdate: true
        prerelease: false
        removeArtifacts: false
        replacesArtifacts: false
        tag: ${{ needs.pre-setup.outputs.git-tag }}
        token: ${{ secrets.GITHUB_TOKEN }}

...