_build.yaml

# This is a trusted builder implemented as a reusable workflow that can be called by other
# Actions workflows. It checks, tests, and builds the artifacts including SBOM and documentations,
# and computes hash digests as output to be used by a SLSA provenance generator. The artifacts are
# always uploaded for every job to be used for debugging purposes, but they will be removed within
# the specified retention days.
#
# Even though we run the build in a matrix to check against different platforms, due to a known
# limitation of reusable workflows that do not support setting strategy property from the caller
# workflow, we only generate artifacts for ubuntu-latest and Python 3.13, which can be used to
# create a release. For details see:
#
# https://docs.github.com/en/actions/using-workflows/reusing-workflows#limitations
#
# Note: if the build workflow needs to access secrets, they need to be passed by the caller using
# `secrets: inherit`. See also
#
# https://docs.github.com/en/actions/using-workflows/reusing-workflows
# https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions
#
# for the security recommendations.

name: Build the package
on:
  workflow_call:
    inputs:
      disable-pip-audit:
        type: boolean
        required: true
        description: Enable or disable running pip_audit to check installed packages for vulnerabilities
permissions:
  contents: read
env:
  RELEASE_OS_X86_64: ubuntu-24.04        # Default OS for x86_64-compatible release artifacts.
  RELEASE_OS_ARM64: ubuntu-24.04-arm     # Default OS for ARM64-compatible release artifacts.
  RELEASE_PYTHON_VERSION: '3.13'         # Default Python version used for release artifacts.

jobs:
  build:
    # Uncomment the following to disable checks and tests for Draft pull requests.
    # if: github.event.pull_request.draft == false
    name: Build Python ${{ matrix.python }} on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        # It is recommended to pin a Runner version specifically:
        # https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners
        os: [ubuntu-24.04, ubuntu-24.04-arm, macos-latest, windows-latest]
        python: ['3.10', '3.11', '3.12', '3.13']

    outputs:
      arch-env: ${{ steps.set-arch-env.outputs.arch_env }}

    steps:

    # Create a GitHub Actions environment variable that maps a matrix.os value to a more descriptive environment
    # value (e.g., ubuntu-x86-64 or ubuntu-arm64).
    - name: Determine architecture label
      id: set-arch-env
      shell: bash
      run: |
        if [[ "${{ matrix.os }}" == "ubuntu-24.04" ]]; then
          echo "arch_env=ubuntu-x86-64" >> "$GITHUB_OUTPUT"
        elif [[ "${{ matrix.os }}" == "ubuntu-24.04-arm" ]]; then
          echo "arch_env=ubuntu-arm64" >> "$GITHUB_OUTPUT"
        else
          echo "arch_env=unknown" >> "$GITHUB_OUTPUT"
        fi

    - name: Test the env variable
      run: echo "Architecture-specific value ${{ steps.set-arch-env.outputs.arch_env }}"

    - name: Harden Runner
      uses: step-security/harden-runner@c6295a65d1254861815972266d5933fd6e532bdf # v2.11.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: Set up Python
      uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
      with:
        python-version: ${{ matrix.python }}

    # Using the Makefile assumes an activated virtual environment, which doesn't exist
    # when running in an Action environment (https://github.com/actions/setup-python/issues/359).
    # Instead we create an empty .venv folder so that the Makefile continues to function
    # while Python operates within the runner's global environment. It is safe to ignore
    # warnings from the Makefile about the missing virtual environment.
    - name: Create empty virtual environment for Actions
      run: mkdir .venv
    - name: Install dependencies
      run: make setup

    # Audit all currently installed packages for security vulnerabilities. This step can
    # be disabled by setting the repository variable DISABLE_PIP_AUDIT to 'true'.
    - name: Audit installed packages
      if: ${{ !inputs.disable-pip-audit }}
      run: make audit

    # Build the sdist and wheel distribution of the package and docs as a zip file.
    # We don't need to check and test the package separately because `make dist` runs
    # those targets first and only builds the package if they succeed. The Hypothesis
    # profile picks the Hypothesis settings (see tests/conftest.py) which, for Github,
    # disable randomized testing to avoid breaking CI.
    - name: Build the package
      run: make dist
      env:
        HYPOTHESIS_PROFILE: github

    # Generate the requirements.txt that contains the hash digests of the dependencies and
    # generate the SBOM using CyclonDX SBOM generator for the release Python version and
    # supported release OS targets.
    - name: Generate requirements.txt and SBOM
      if: >
        matrix.python == env.RELEASE_PYTHON_VERSION &&
        (matrix.os == env.RELEASE_OS_X86_64 || matrix.os == env.RELEASE_OS_ARM64)
      run: make requirements sbom

    # Remove the old requirements.txt file (which includes _all_ packages) and generate a
    # new one for the package and its actual and required dependencies only. Run this step
    # for the release Python version and supported release OS targets only.
    - name: Prune packages and generate required requirements.txt
      if: >
        matrix.python == env.RELEASE_PYTHON_VERSION &&
        (matrix.os == env.RELEASE_OS_X86_64 || matrix.os == env.RELEASE_OS_ARM64)
      run: |
        rm requirements.txt
        make prune requirements

    # Find the paths to the artifact files that will be included in the release, compute
    # the SHA digest for all the release files and encode them using Base64, and export it
    # from this job. Run this step for the release Python version and supported release
    # OS targets only.
    - name: Compute package hash
      if: >
        matrix.python == env.RELEASE_PYTHON_VERSION &&
        (matrix.os == env.RELEASE_OS_X86_64 || matrix.os == env.RELEASE_OS_ARM64)
      id: compute-hash
      shell: bash
      run: |
        set -euo pipefail
        TARBALL_PATH=$(find dist/ -type f -name "*.tar.gz")
        WHEEL_PATH=$(find dist/ -type f -name "*.whl")
        REQUIREMENTS_PATH=$(find dist/ -type f -name "*-requirements.txt")
        SBOM_PATH=$(find dist/ -type f -name "*-sbom.json")
        HTML_DOCS_PATH=$(find dist/ -type f -name "*-docs-html.zip")
        MARKDOWN_DOCS_PATH=$(find dist/ -type f -name "*-docs-md.zip")
        BUILD_EPOCH_PATH=$(find dist/ -type f -name "*-build-epoch.txt")
        sha256sum --version
        DIGEST=$(sha256sum "$TARBALL_PATH" "$WHEEL_PATH" "$REQUIREMENTS_PATH" "$SBOM_PATH" "$HTML_DOCS_PATH" "$MARKDOWN_DOCS_PATH" "$BUILD_EPOCH_PATH" | base64 -w0)
        echo "Digest of artifacts is $DIGEST."
        echo "$DIGEST" > artifacts-sha256-file-${{ steps.set-arch-env.outputs.arch_env }}

    # Currently reusable workflows do not support setting strategy property from the caller workflow.
    # Run this step for the release Python version and supported release OS targets only.
    - name: Upload the package artifact for debugging and release
      if: >
        matrix.python == env.RELEASE_PYTHON_VERSION &&
        (matrix.os == env.RELEASE_OS_X86_64 || matrix.os == env.RELEASE_OS_ARM64)
      uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
      with:
        name: artifacts-${{ steps.set-arch-env.outputs.arch_env }}
        path: ./dist*/
        if-no-files-found: error
        retention-days: 7

    # Run this step for the release Python version and supported release OS targets only.
    - name: Upload artifacts-sha256
      if: >
        matrix.python == env.RELEASE_PYTHON_VERSION &&
        (matrix.os == env.RELEASE_OS_X86_64 || matrix.os == env.RELEASE_OS_ARM64)
      uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
      with:
        name: artifacts-sha256-file-${{ steps.set-arch-env.outputs.arch_env }}
        path: artifacts-sha256-file-${{ steps.set-arch-env.outputs.arch_env }}
        retention-days: 7