BuildPythonWheels.yml

name: 'Wheel Builder'
description: 'Build Binary wheels for a Python project'

on:
  workflow_call:
    inputs:
      dockerfile:
        description: 'Dockerfile to use for ManyLinux builds'
        type: string
        required: false
        default: './docker/Dockerfile.python_wheels'
      context:
        description: 'Context to pass into container'
        type: string
        required: false
        default: '.'
      py_versions:
        description: 'Versions of Python to build against'
        type: string
        required: false
        default: '["3.10", "3.11", "3.12", "3.13", "3.14"]'
      mnl_versions:
        description: 'Versions of ManyLinux to build against'
        type: string
        required: false
        default: '["2_28", "2_34", "2_39"]'
      cache_mode:
        description: 'Container cache mode min/max'
        type: string
        required: false
        default: 'max'
      maximize_space:
        description: 'Remove tens of GBs of GH supplied junk before the build'
        type: boolean
        required: false
        default: false
      docker_logs:
        description: 'Upload Docker build logs and summaries'
        type: boolean
        required: false
        default: false
      push_build_results:
        description: 'Push built wheel container images to the registry'
        type: boolean
        required: false
        default: true
      ghcr_repo:
        description: 'Name of the GHCR.io repo'
        type: string
        required: false
        default: ${{ github.repository_owner }}/${{ github.event.repository.name }}
      buildkit_image:
        description: 'BuildKit image to use for docker/setup-buildx-action'
        type: string
        required: false
        default: 'moby/buildkit:buildx-stable-1'
      qemu_image:
        description: 'Binfmt image to use for QEMU static binaries'
        type: string
        required: false
        default: 'tonistiigi/binfmt:latest'
      qemu_image_cache_key:
        description: 'Optional actions/cache key for a pre-cached QEMU binfmt image'
        type: string
        required: false
        default: ''
      qemu_image_cache_path:
        description: 'Optional actions/cache path for a pre-cached QEMU binfmt image'
        type: string
        required: false
        default: ''
      qemu_image_cache_tar:
        description: 'Optional tarball path for a pre-cached QEMU binfmt image'
        type: string
        required: false
        default: ''
      buildkit_image_cache_key:
        description: 'Optional actions/cache key for a pre-cached BuildKit image'
        type: string
        required: false
        default: ''
      buildkit_image_cache_path:
        description: 'Optional actions/cache path for a pre-cached BuildKit image'
        type: string
        required: false
        default: ''
      buildkit_image_cache_tar:
        description: 'Optional tarball path for a pre-cached BuildKit image'
        type: string
        required: false
        default: ''

jobs:
  cache_qemu_image:
    name: Cache QEMU Image
    if: ${{ inputs.qemu_image_cache_key == '' || inputs.qemu_image_cache_path == '' || inputs.qemu_image_cache_tar == '' }}
    uses: ./.github/workflows/GetCachedContainer.yml
    with:
      image: ${{ inputs.qemu_image }}
      platforms: host
      cache-key-prefix: qemu-binfmt-image
      cache-name: qemu-binfmt-image

  cache_buildkit_image:
    name: Cache BuildKit Image
    if: ${{ inputs.buildkit_image_cache_key == '' || inputs.buildkit_image_cache_path == '' || inputs.buildkit_image_cache_tar == '' }}
    uses: ./.github/workflows/GetCachedContainer.yml
    with:
      image: ${{ inputs.buildkit_image }}
      platforms: host
      cache-key-prefix: buildkit-image
      cache-name: buildkit-image

  cache_registry_image:
    name: Cache Local Registry Image
    uses: ./.github/workflows/GetCachedContainer.yml
    with:
      image: registry:2
      platforms: host
      cache-key-prefix: registry-image
      cache-name: registry-image

  cache_manylinux_image:
    name: Cache ManyLinux Image
    strategy:
      fail-fast: false
      matrix:
        mnl-version: ${{ fromJson(inputs.mnl_versions) }}
    uses: ./.github/workflows/GetCachedContainer.yml
    with:
      image: quay.io/pypa/manylinux_${{ matrix.mnl-version }}:latest
      # Avoid remote manifest inspection here; platforms are read from the local registry copy below.
      platforms: ''
      cache-key-prefix: manylinux-image
      cache-name: manylinux-${{ matrix.mnl-version }}-image
      cache-version: oci-v1
      archive-format: oci
      archive-reference: cached-image:latest

  ccache_image_matrix:
    name: Generate CCache Image Matrix
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.ccache-matrix.outputs.matrix }}
    steps:
    - name: Generate CCache image matrix
      id: ccache-matrix
      env:
        MNL_VERSIONS: ${{ inputs.mnl_versions }}
      run: |
        set -euo pipefail
        MATRIX="$(printf '%s' "${MNL_VERSIONS}" | jq -c '[.[] as $version | {
          "mnl_version": $version,
          "image": ("ghcr.io/sobomax/ccache:latest-manylinux-" + ($version | gsub("_"; "."))),
          "cache_name": ("ccache-manylinux-" + $version + "-image")
        }]')"
        echo "matrix=${MATRIX}" >> "${GITHUB_OUTPUT}"

  cache_ccache_image:
    name: Cache CCache Image
    needs: ccache_image_matrix
    strategy:
      fail-fast: false
      matrix:
        ccache: ${{ fromJson(needs.ccache_image_matrix.outputs.matrix) }}
    uses: ./.github/workflows/GetCachedContainer.yml
    with:
      image: ${{ matrix.ccache.image }}
      cache-key-prefix: ccache-image
      cache-name: ${{ matrix.ccache.cache_name }}
      cache-version: oci-v1
      archive-format: oci
      archive-reference: cached-image:latest

  bin:
    name: ManyLinux
    runs-on: ubuntu-latest
    if: ${{ always() && !cancelled() && needs.cache_qemu_image.result != 'failure' && needs.cache_qemu_image.result != 'cancelled' && needs.cache_buildkit_image.result != 'failure' && needs.cache_buildkit_image.result != 'cancelled' && needs.cache_registry_image.result != 'failure' && needs.cache_registry_image.result != 'cancelled' && needs.cache_manylinux_image.result != 'failure' && needs.cache_manylinux_image.result != 'cancelled' && needs.cache_ccache_image.result != 'failure' && needs.cache_ccache_image.result != 'cancelled' }}
    needs:
    - cache_qemu_image
    - cache_buildkit_image
    - cache_registry_image
    - cache_manylinux_image
    - cache_ccache_image
    permissions:
      packages: write
    env:
      PY_VER: ${{ matrix.python-version }}
      BASE_IMAGE: quay.io/pypa/manylinux_${{ matrix.mnl-version }}:latest
      BASE_KIND: manylinux
      MNL_VERSION: ${{ matrix.mnl-version }}
      MANYLINUX_IMAGE_CACHE_VERSION: oci-v1
      MANYLINUX_IMAGE_ARCHIVE_REF: cached-image:latest
      CCACHE_IMAGE_CACHE_VERSION: oci-v1
      CCACHE_IMAGE_ARCHIVE_REF: cached-image:latest
      GHCR_REPO: ghcr.io/${{ inputs.ghcr_repo }}
      BUILD_SUFX: py${{ matrix.python-version }}-mnl${{ matrix.mnl-version }}
    strategy:
      fail-fast: false
      matrix:
        python-version: ${{ fromJson(inputs.py_versions) }}
        mnl-version: ${{ fromJson(inputs.mnl_versions) }}
    steps:
    - name: Maximize build space
      if: ${{ inputs.maximize_space }}
      shell: sh -x -e {0}
      run: &maximize_build_space |
        echo "Memory and swap:"
        sudo free -h
        echo
        sudo swapon --show
        echo

        echo "Available storage:"
        sudo df -h
        echo

        PIDS=""
        for d in /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL
        do
          sudo rm -rf "${d}" &
          PIDS="${PIDS} ${!}"
        done
        sudo docker image prune --all --force &
        PIDS="${PIDS} ${!}"
        for pid in ${PIDS}
        do
          wait ${pid}
        done

    - uses: actions/checkout@v6

    - name: Set up Python ${{ env.PY_VER }}
      uses: actions/setup-python@v6
      with:
        python-version: ${{ env.PY_VER }}

    - name: Set dynamic environment
      id: set-env
      shell: bash -o pipefail {0}
      run: &set_dynamic_environment |
        GIT_BRANCH="${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}"
        GIT_BRANCH="${GIT_BRANCH#refs/tags/}"
        BUILD_IMAGE="${GHCR_REPO}:${GIT_BRANCH}-${BUILD_SUFX}"
        D_CACHE_IMAGE="${GHCR_REPO}-buildcache:${GIT_BRANCH}-${BUILD_SUFX}"
        if [ "${{ github.event_name }}" != 'pull_request' ]
        then
          CACHE_IMAGE="scratch"
          for ci in "${BUILD_IMAGE}" "${GHCR_REPO}:master-${BUILD_SUFX}"
          do
            if docker manifest inspect ${ci} >/dev/null 2>/dev/null
            then
              CACHE_IMAGE="${ci}"
              break
            fi
          done
          CACHE_SPEC="type=registry,ref=${D_CACHE_IMAGE}"
          DO_PUSH="${{ inputs.push_build_results }}"
        else
          CACHE_IMAGE="scratch"
          CACHE_SPEC="gha"
          DO_PUSH="false"
        fi
        case "${BASE_KIND}" in
          manylinux)
            CCACHE_MNL_TAG="$(printf '%s' "${MNL_VERSION}" | sed 's|_|.|g')"
            CCACHE_IMG_TAG="manylinux-${CCACHE_MNL_TAG}"
            CCACHE_IMAGE="ghcr.io/sobomax/ccache:latest-${CCACHE_IMG_TAG}"
            PY_SVER="3${PY_VER#3.}"
            PYTHON_CMD="/opt/python/cp${PY_SVER}-cp${PY_SVER}/bin/python"
            ;;
          *)
            echo "Unsupported base image kind: ${BASE_KIND}" >&2
            exit 1
            ;;
        esac
        TIMESTAMP="`git log -1 --pretty=%ct`"
        echo "Build Image: ${BUILD_IMAGE}"
        echo "Cache Image: ${CACHE_IMAGE}"
        echo "CCache Image: ${CCACHE_IMAGE}"
        echo "Timestamp: ${TIMESTAMP}"
        echo "CACHE_SPEC=${CACHE_SPEC}" >> $GITHUB_ENV
        echo "PYTHON_CMD=${PYTHON_CMD}" >> $GITHUB_ENV
        echo "BUILD_IMAGE=${BUILD_IMAGE}" >> $GITHUB_ENV
        echo "CACHE_IMAGE=${CACHE_IMAGE}" >> $GITHUB_ENV
        echo "CCACHE_IMAGE=${CCACHE_IMAGE}" >> $GITHUB_ENV
        echo "DO_PUSH=${DO_PUSH}" >> $GITHUB_ENV
        echo "CCACHE_IMG_TAG=${CCACHE_IMG_TAG}" >> $GITHUB_ENV
        echo "TIMESTAMP=${TIMESTAMP}" >> $GITHUB_ENV

    - name: Restore QEMU binfmt image cache
      uses: actions/cache/restore@v5
      with:
        path: ${{ inputs.qemu_image_cache_key != '' && inputs.qemu_image_cache_path != '' && inputs.qemu_image_cache_tar != '' && inputs.qemu_image_cache_path || needs.cache_qemu_image.outputs.image-cache-path }}
        key: ${{ inputs.qemu_image_cache_key != '' && inputs.qemu_image_cache_path != '' && inputs.qemu_image_cache_tar != '' && inputs.qemu_image_cache_key || needs.cache_qemu_image.outputs.image-cache-key }}
        fail-on-cache-miss: true

    - name: Load QEMU binfmt image
      run: docker load --input "${{ inputs.qemu_image_cache_key != '' && inputs.qemu_image_cache_path != '' && inputs.qemu_image_cache_tar != '' && inputs.qemu_image_cache_tar || needs.cache_qemu_image.outputs.image-cache-tar }}"

    - name: Set up QEMU
      env:
        QEMU_IMAGE: ${{ inputs.qemu_image }}
      run: |
        set -euo pipefail
        docker image inspect "${QEMU_IMAGE}" >/dev/null
        docker run --rm --privileged "${QEMU_IMAGE}" --version
        docker run --rm --privileged "${QEMU_IMAGE}" --install all

    - name: Restore BuildKit image cache
      uses: actions/cache/restore@v5
      with:
        path: ${{ inputs.buildkit_image_cache_key != '' && inputs.buildkit_image_cache_path != '' && inputs.buildkit_image_cache_tar != '' && inputs.buildkit_image_cache_path || needs.cache_buildkit_image.outputs.image-cache-path }}
        key: ${{ inputs.buildkit_image_cache_key != '' && inputs.buildkit_image_cache_path != '' && inputs.buildkit_image_cache_tar != '' && inputs.buildkit_image_cache_key || needs.cache_buildkit_image.outputs.image-cache-key }}
        fail-on-cache-miss: true

    - name: Load BuildKit image
      run: docker load --input "${{ inputs.buildkit_image_cache_key != '' && inputs.buildkit_image_cache_path != '' && inputs.buildkit_image_cache_tar != '' && inputs.buildkit_image_cache_tar || needs.cache_buildkit_image.outputs.image-cache-tar }}"

    - name: Restore local registry image cache
      uses: actions/cache/restore@v5
      with:
        path: ${{ needs.cache_registry_image.outputs.image-cache-path }}
        key: ${{ needs.cache_registry_image.outputs.image-cache-key }}
        fail-on-cache-miss: true

    - name: Load local registry image
      run: docker load --input "${{ needs.cache_registry_image.outputs.image-cache-tar }}"

    - name: Compute ManyLinux image cache metadata
      id: manylinux-cache
      env:
        DOCKER_IMAGE: ${{ env.BASE_IMAGE }}
      run: |
        set -euo pipefail
        CACHE_NAME="manylinux-${{ matrix.mnl-version }}-image"
        HASH_INPUT="$(printf '%s\n%s\n%s' "${DOCKER_IMAGE}" "" "${MANYLINUX_IMAGE_CACHE_VERSION}")"
        IMAGE_HASH="$(printf '%s' "${HASH_INPUT}" | sha256sum | cut -c1-16)"
        CACHE_DIR="${RUNNER_TEMP}/${CACHE_NAME}-cache"
        IMAGE_TAR="${CACHE_DIR}/${CACHE_NAME}.tar"
        IMAGE_CACHE_KEY="manylinux-image-${RUNNER_OS}-${IMAGE_HASH}"
        echo "image-cache-key=${IMAGE_CACHE_KEY}" >> "${GITHUB_OUTPUT}"
        echo "image-cache-path=${CACHE_DIR}" >> "${GITHUB_OUTPUT}"
        echo "image-cache-tar=${IMAGE_TAR}" >> "${GITHUB_OUTPUT}"

    - name: Restore ManyLinux image cache
      uses: actions/cache/restore@v5
      with:
        path: ${{ steps.manylinux-cache.outputs.image-cache-path }}
        key: ${{ steps.manylinux-cache.outputs.image-cache-key }}
        fail-on-cache-miss: true

    - name: Compute CCache image cache metadata
      id: ccache-cache
      env:
        DOCKER_IMAGE: ${{ env.CCACHE_IMAGE }}
      run: |
        set -euo pipefail
        MANIFEST_JSON="$(docker manifest inspect "${DOCKER_IMAGE}")"
        PLATFORMS="$(printf '%s' "${MANIFEST_JSON}" | \
          jq -r 'if .manifests then .manifests[] | "\(.platform.os)/\(.platform.architecture)\(if .platform.variant != null then "/\(.platform.variant)" else "" end)" else empty end' | \
          sort -u | grep -v unknown | paste -sd ',' || true)"
        if [ -z "${PLATFORMS}" ]
        then
          echo "No manifest-list platforms found for ${DOCKER_IMAGE}; restoring the default image cache."
        fi
        CACHE_NAME="ccache-manylinux-${{ matrix.mnl-version }}-image"
        HASH_INPUT="$(printf '%s\n%s\n%s' "${DOCKER_IMAGE}" "${PLATFORMS}" "${CCACHE_IMAGE_CACHE_VERSION}")"
        IMAGE_HASH="$(printf '%s' "${HASH_INPUT}" | sha256sum | cut -c1-16)"
        CACHE_DIR="${RUNNER_TEMP}/${CACHE_NAME}-cache"
        IMAGE_TAR="${CACHE_DIR}/${CACHE_NAME}.tar"
        IMAGE_CACHE_KEY="ccache-image-${RUNNER_OS}-${IMAGE_HASH}"
        echo "image-cache-key=${IMAGE_CACHE_KEY}" >> "${GITHUB_OUTPUT}"
        echo "image-cache-path=${CACHE_DIR}" >> "${GITHUB_OUTPUT}"
        echo "image-cache-tar=${IMAGE_TAR}" >> "${GITHUB_OUTPUT}"

    - name: Restore CCache image cache
      uses: actions/cache/restore@v5
      with:
        path: ${{ steps.ccache-cache.outputs.image-cache-path }}
        key: ${{ steps.ccache-cache.outputs.image-cache-key }}
        fail-on-cache-miss: true

    - name: Start local image registry
      run: |
        set -euo pipefail
        docker run -d --name local-registry -p 5000:5000 registry:2
        for attempt in $(seq 1 30)
        do
          if curl -fsS http://localhost:5000/v2/ >/dev/null
          then
            exit 0
          fi
          sleep 1
        done
        echo "Local image registry did not become ready." >&2
        docker logs local-registry >&2 || true
        exit 1

    - name: Install Skopeo
      run: |
        set -euo pipefail
        if ! command -v skopeo >/dev/null 2>&1
        then
          sudo apt-get update
          sudo apt-get install -y skopeo
        fi

    - name: Login to GitHub Container Registry
      uses: docker/login-action@v4
      if: github.event_name != 'pull_request'
      with:
        registry: ghcr.io
        username: ${{ github.repository_owner }}
        password: ${{ secrets.GITHUB_TOKEN }}

    - name: Publish ManyLinux image to local registry
      id: local-manylinux
      env:
        LOCAL_IMAGE: localhost:5000/pypa/manylinux_${{ matrix.mnl-version }}:latest
      run: |
        set -euo pipefail
        skopeo copy --all \
          --dest-tls-verify=false \
          "oci-archive:${{ steps.manylinux-cache.outputs.image-cache-tar }}:${MANYLINUX_IMAGE_ARCHIVE_REF}" \
          "docker://${LOCAL_IMAGE}"
        PLATFORMS="$(skopeo inspect --raw --tls-verify=false "docker://${LOCAL_IMAGE}" | \
          jq -r '.manifests[] | "\(.platform.os)/\(.platform.architecture)\(if .platform.variant != null then "/\(.platform.variant)" else "" end)"' | \
          sort -u | grep -v unknown | paste -sd ',')"
        if [ -z "${PLATFORMS}" ]
        then
          echo "Cannot get list of platforms supported by ${LOCAL_IMAGE}." >&2
          exit 1
        fi
        echo "Platforms: ${PLATFORMS}"
        echo "image=${LOCAL_IMAGE}" >> "${GITHUB_OUTPUT}"
        echo "PLATFORMS=${PLATFORMS}" >> "${GITHUB_ENV}"

    - name: Load CCache image into local registry
      id: local-ccache
      env:
        LOCAL_IMAGE: localhost:5000/sobomax/ccache:latest-${{ env.CCACHE_IMG_TAG }}
      run: |
        set -euo pipefail
        skopeo copy --all \
          --dest-tls-verify=false \
          "oci-archive:${{ steps.ccache-cache.outputs.image-cache-tar }}:${CCACHE_IMAGE_ARCHIVE_REF}" \
          "docker://${LOCAL_IMAGE}"
        echo "image=${LOCAL_IMAGE}" >> "${GITHUB_OUTPUT}"

    - name: Load cache image into local registry
      id: local-cache-image
      env:
        LOCAL_IMAGE: localhost:5000/build-cache/wheels:${{ env.BUILD_SUFX }}
      run: |
        set -euo pipefail
        if [ "${CACHE_IMAGE}" = "scratch" ]
        then
          echo "image=scratch" >> "${GITHUB_OUTPUT}"
          exit 0
        fi
        skopeo copy --all \
          --dest-tls-verify=false \
          "docker://${CACHE_IMAGE}" \
          "docker://${LOCAL_IMAGE}"
        echo "image=${LOCAL_IMAGE}" >> "${GITHUB_OUTPUT}"

    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v4
      with:
        driver-opts: |
          image=${{ inputs.buildkit_image }}
          network=host
        buildkitd-config-inline: |
          [registry."localhost:5000"]
            http = true
            insecure = true

    - name: Build Binary Wheels
      uses: docker/build-push-action@v7
      env:
        SOURCE_DATE_EPOCH: ${{ env.TIMESTAMP }}
        DOCKER_BUILD_SUMMARY: ${{ inputs.docker_logs }}
        DOCKER_BUILD_RECORD_UPLOAD: ${{ inputs.docker_logs }}
      with:
        context: ${{ inputs.context }}
        file: ${{ inputs.dockerfile }}
        build-args: |
          BASE_IMAGE=${{ steps.local-manylinux.outputs.image }}
          PY_VER=${{ env.PY_VER }}
          PYTHON_CMD=${{ env.PYTHON_CMD }}
          CACHE_IMAGE=${{ steps.local-cache-image.outputs.image }}
          CCACHE_IMAGE=${{ steps.local-ccache.outputs.image }}
        platforms: ${{ env.PLATFORMS }}
        tags: ${{ env.BUILD_IMAGE }}
        push: ${{ env.DO_PUSH }}
        outputs: type=local,dest=dist_out
        cache-from: ${{ env.CACHE_SPEC }}
        cache-to: ${{ env.CACHE_SPEC }},mode=${{ inputs.cache_mode }},compression=zstd

    - name: Collect Wheels
      run: |
        mkdir dist
        mv `find dist_out -type f -name \*.whl | grep -v '/root/[.]cache/pip'` dist
        rm -r dist_out

    - name: Upload Wheels
      uses: actions/upload-artifact@v7
      with:
        name: dist-${{ env.BUILD_SUFX }}
        path: dist