release.yaml

# We run checks on pushing to the specified branches.
# Pushing to main also triggers a release.

name: Check and Release
on:
  push:
    branches:
    - main
    - staging
permissions:
  contents: read

jobs:
  check:
    if: ${{ !startsWith(github.event.commits[0].message, 'bump:') }}
    uses: ./.github/workflows/_build.yaml
    permissions:
      contents: read
    with:
      disable-pip-audit: ${{ vars.DISABLE_PIP_AUDIT == 'true' }}

  # On pushes to the 'main' branch create a new release by bumping the version
  # and generating a change log. That's the new bump commit and associated tag.
  bump:
    needs: check
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:

    - name: Harden Runner
      uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
      with:
        egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
        disable-sudo: true

    - name: Check out repository
      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      with:
        fetch-depth: 0
        token: ${{ secrets.REPO_ACCESS_TOKEN }}

    - name: Set up Python
      uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
      with:
        python-version: '3.13'

    - name: Set up Commitizen
      run: |
        pip install --upgrade pip wheel
        pip install 'commitizen ==3.31.0'

    - name: Set up user
      run: |
        git config --global user.name "$USER_NAME"
        git config --global user.email "$USER_EMAIL"
        git config --list --global # For debug purposes.
      env:
        # This is the username and email for the user who commits and pushes the release
        # commit. In an organisation that should be a dedicated devops account.
        USER_NAME: jenstroeger
        USER_EMAIL: jenstroeger@users.noreply.github.com

    # In some cases a user may merge commits that don't cause a version bump, which causes commitizen
    # to fail with error code 21 (NoneIncrementExit). Thus we silence that particular error to avoid
    # failing this job: https://commitizen-tools.github.io/commitizen/bump/#avoid-raising-errors
    # Furthermore, if the version strings have inconsistent versions then `cz` and CI fail such that
    # the issue can be inspected and fixed.
    - name: Create changelog and bump
      run: cz --no-raise 21 bump --changelog --check-consistency --yes

    - name: Push the release
      run: |
        git push
        git push --tags

  # When triggered by the version bump commit, build the package and publish the release artifacts.
  build:
    if: github.ref == 'refs/heads/main' && startsWith(github.event.commits[0].message, 'bump:')
    uses: ./.github/workflows/_build.yaml
    permissions:
      contents: read
    with:
      disable-pip-audit: ${{ vars.DISABLE_PIP_AUDIT == 'true' }}

  # Create a new Release on Github from the verified build artifacts, and optionally
  # publish the artifacts to a PyPI server.
  release:
    needs: [build]
    name: Release
    outputs:
      release-tag: ${{ steps.upload-assets.outputs.release-tag }}
      release-url: ${{ steps.upload-assets.outputs.release-url }}
    runs-on: ubuntu-latest
    permissions:
      contents: write # To publish release notes.
    steps:

    - name: Harden Runner
      uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
      with:
        egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
        disable-sudo: true

    - name: Check out repository
      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      with:
        fetch-depth: 0

    - name: Download artifact
      uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
      with:
        name: artifact-ubuntu-latest-python-3.13
        path: dist

    # Verify hashes by first computing hashes for the artifacts and then comparing them
    # against the hashes computed by the build job.
    - name: Verify the artifact hash
      env:
        ARTIFACT_HASH: ${{ needs.build.outputs.artifacts-sha256 }}
      run: |
        set -euo pipefail
        echo "Hash of package should be $ARTIFACT_HASH."
        echo "$ARTIFACT_HASH" | base64 --decode | sha256sum --strict --check --status || exit 1

    # Create the Release Notes using commitizen.
    - name: Set up Python
      uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
      with:
        python-version: '3.13'

    - name: Set up Commitizen
      run: |
        pip install --upgrade pip wheel
        pip install 'commitizen ==3.31.0'

    - name: Create Release Notes
      run: cz changelog --dry-run "$(cz version --project)" > RELEASE_NOTES.md

    # Create the release including the artifacts and the SLSA L3 provenance.
    - name: Upload assets
      id: upload-assets
      env:
        GH_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
      run: |
        TAG=$(git describe --tags --abbrev=0)
        gh release create "$TAG" dist/* --title "$TAG" --notes-file RELEASE_NOTES.md
        echo "release-tag=$TAG" >> "$GITHUB_OUTPUT"
        echo "release-url=$(gh release view """$TAG""" --json url --jq .url)" >> "$GITHUB_OUTPUT"

    # Uncomment the following steps to publish to a PyPI server.
    # At the moment PyPI does not provide a mechanism to publish
    # the provenance. So, users have to download the provenance from
    # the release page of the GitHub repository to verify the artifact.
    # Install Twine without using the package's Makefile to avoid
    # installing unnecessary dependencies, which is slow.
    # - name: Set up Twine
    #   run: |
    #     pip install --upgrade pip wheel
    #     pip install 'twine ==4.0.2'

    # Pass the username, password, and PYPI repository URL via env variables.
    # Read the password from GitHub secrets or via other trusted mechanisms.
    # Do not hardcode the password in the workflow.
    # - name: Publish to PyPI server
    #   run: twine upload --verbose --skip-existing dist/*.tar.gz dist/*.whl
    #   env:
    #     TWINE_USERNAME=<USERNAME>
    #     TWINE_PASSWORD=<PASSWORD>
    #     TWINE_REPOSITORY_URL=<REPOSITORY_URL>

  # Generate the build provenance. The generator should be referenced with a semantic version.
  # The build will fail if we reference it using the commit SHA. To avoid using a pre-built
  # provenance generator which depends on an external service Rekor (https://github.com/sigstore/rekor)
  # we build this generator from source for now. For more information see this discussion:
  # https://github.com/slsa-framework/slsa-github-generator/issues/942
  provenance:
    needs: [build, release]
    uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v2.0.0
    with:
      base64-subjects: ${{ needs.build.outputs.artifacts-sha256 }}
      compile-generator: false # Do not build the provenance generator from source anymore.
      # Set private-repository to true for private repositories. Note that the repository name is
      # uploaded as part of the transparency log entry on the public Rekor instance (rekor.sigstore.dev).
      private-repository: false
    permissions:
      actions: read # To read the workflow path.
      id-token: write # To sign the provenance.
      contents: write # To add assets to a release.

  # Publish the SLSA provenance as the GitHub release asset.
  publish_provenance:
    needs: [release, provenance]
    name: Publish provenance
    runs-on: ubuntu-latest
    permissions:
      contents: write # To publish release notes.
    steps:

    - name: Harden Runner
      uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1
      with:
        egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
        disable-sudo: true

    - name: Check out repository
      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      with:
        fetch-depth: 0

    - name: Download provenance
      uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
      with:
        name: ${{ needs.provenance.outputs.provenance-name }}

    - name: Upload provenance
      run: gh release upload ${{ needs.release.outputs.release-tag }} ${{ needs.provenance.outputs.provenance-name }}
      env:
        GH_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}

  # Send out release notifications after the Release was published on GitHub.
  # Uncomment the `if` to disable sending release notifications.
  notifications:
    # if: ${{ false }}
    needs: [release]
    name: Send Release notifications
    uses: ./.github/workflows/_release-notifications.yaml
    permissions:
      contents: read
    with:
      repo-name: ${{ github.event.repository.name }}
      release-tag: ${{ needs.release.outputs.release-tag }}
      release-url: ${{ needs.release.outputs.release-url }}
    secrets:
      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

  # Publish the generated Markdown documentation to the repository's Wiki.
  # Uncomment the `if` to disable generating Wiki documentation.
  wiki:
    # if: ${{ false }}
    needs: [release]
    name: Publish Github Wiki documentation
    uses: ./.github/workflows/_wiki-documentation.yaml
    permissions:
      contents: read
    with:
      release-tag: ${{ needs.release.outputs.release-tag }}
      release-url: ${{ needs.release.outputs.release-url }}
      # Github disallows passing environment variables as arguments to a reusable
      # workflow, so we have to duplicate these values here. Related discussion
      # here: https://github.com/actions/toolkit/issues/931
      artifact-name: artifact-ubuntu-latest-python-3.13
      git-user-name: jenstroeger
      git-user-email: jenstroeger@users.noreply.github.com
    secrets:
      REPO_ACCESS_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}

  # After the bump commit was pushed to the main branch, rebase the staging branch
  # (to_head argument) on top of the new main branch (from_base argument), to keep
  # the histories of both branches in sync.
  rebase_staging:
    # if: ${{ false }}
    needs: [release]
    name: Rebase staging branch on main
    uses: ./.github/workflows/_generate-rebase.yaml
    permissions:
      contents: read
    with:
      to-head: staging
      from-base: origin/main
      git-user-name: jenstroeger
      git-user-email: jenstroeger@users.noreply.github.com
    secrets:
      REPO_ACCESS_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}