release-linux.yml

name: Release Linux & macOS binaries

# Triggered when a GitHub Release is published. Builds .so binaries for
# Linux glibc 2.35 (x86_64 + arm64) and macOS 12+ arm64 at PHP 8.4 + 8.5 (NTS
# binaries; supported Unix ZTS installs build from source), uploads each as a release asset
# via php/pie-ext-binary-builder using PIE's pre-packaged-binary naming
# convention. PIE's `pie install iliaal/php_clickhouse` then resolves
# the prebuilt asset matching the host arch/os/libc/PHP-version instead
# of building clickhouse-cpp from source (~3-5 min compile).
#
# Coverage matrix: 3 lanes x 2 PHP = 6 prebuilt assets per release.
#
# macOS Intel (macos-13) is intentionally absent: GitHub's Intel runner
# pool is too contended to ship reliably, and macOS 26 drops Intel
# support anyway. Intel-Mac users get source-build via PIE's
# composer-default fallback.
#
# Linux musl is deferred: shivammathur/setup-php in Alpine containers
# needs more setup; users on musl get source-build via PIE's
# composer-default fallback meanwhile.
#
# This workflow + the existing release-windows.yml together produce
# 6 Linux/macOS + 12 Windows = 18 prebuilt assets per release.

on:
  release:
    types: [published]
  # Manual trigger. Two uses:
  #   - blank release_tag  -> build every lane (build-only validation step
  #     below), no upload. The /release-ext Step 9.5 pre-tag gate.
  #   - release_tag set    -> build that tag's source and upload to it (backfill,
  #     e.g. when this workflow was added after the tag existed).
  workflow_dispatch:
    inputs:
      release_tag:
        description: 'Existing tag to build + upload to. Blank = build-only validation (no upload).'
        required: false
        default: ''

permissions: {}

concurrency:
  group: release-linux-${{ github.event.release.tag_name || inputs.release_tag || github.ref }}
  cancel-in-progress: false

jobs:
  build:
    name: ${{ matrix.platform.os }} php ${{ matrix.php }}
    runs-on: ${{ matrix.platform.os }}
    permissions:
      contents: write # Uploads built archives to the selected release.
    strategy:
      fail-fast: false
      matrix:
        # The generic Linux archive carries no distribution baseline in its
        # filename, so both architectures build on Ubuntu 22.04 / glibc 2.35.
        # macOS builds on the current arm64 image with an explicit deployment
        # target; the post-build gate verifies the actual binary metadata.
        platform:
          - os: ubuntu-22.04
            compat_mode: --linux-glibc
            compat_maximum: '2.35'
            macos_target: ''
          - os: ubuntu-22.04-arm
            compat_mode: --linux-glibc
            compat_maximum: '2.35'
            macos_target: ''
          - os: macos-15
            compat_mode: --macos-min
            compat_maximum: '12.0'
            macos_target: '12.0'
        php:
          - '8.4'
          - '8.5'
    env:
      MACOSX_DEPLOYMENT_TARGET: ${{ matrix.platform.macos_target }}
    steps:
      # release -> the tag; dispatch-with-tag -> that tag; blank -> triggering branch.
      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          ref: ${{ github.event.release.tag_name || inputs.release_tag }}
          persist-credentials: false

      - name: Setup PHP
        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2
        with:
          php-version: ${{ matrix.php }}
          coverage: none

      # Checked out ahead of the build so the pre-upload gate below can use the
      # current checker even when the released tag predates it.
      - name: Checkout verification tools
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          ref: ${{ github.sha }}
          path: .release-tools
          sparse-checkout: scripts/check-release-binary.sh
          sparse-checkout-cone-mode: false
          persist-credentials: false

      # pie-ext-binary-builder fuses build + upload into one action, so by the
      # time its artifact can be inspected it is already attached to the
      # release. Build an equivalent binary on the same runner first and gate
      # on that. Costs one extra compile per release lane; the alternative is
      # publishing a binary whose runtime ceiling was never checked.
      - name: Pre-upload binary compatibility gate
        if: github.event_name == 'release' || inputs.release_tag != ''
        env:
          COMPAT_MAXIMUM: ${{ matrix.platform.compat_maximum }}
          COMPAT_MODE: ${{ matrix.platform.compat_mode }}
        run: |
          set -euo pipefail
          gate_dir="$RUNNER_TEMP/precheck"
          rm -rf "$gate_dir"
          mkdir -p "$gate_dir"
          tar -cf - --exclude=.git --exclude=.release-tools . | tar -xf - -C "$gate_dir"
          cd "$gate_dir"
          phpize
          ./configure --enable-clickhouse
          if command -v nproc >/dev/null 2>&1; then
            jobs=$(nproc)
          else
            jobs=$(sysctl -n hw.ncpu)
          fi
          make -j"$jobs"
          "$GITHUB_WORKSPACE/.release-tools/scripts/check-release-binary.sh" \
            "$COMPAT_MODE" \
            "$COMPAT_MAXIMUM" \
            "$gate_dir/modules/clickhouse.so"

      - name: Build and upload prebuilt binary
        id: prebuilt
        if: github.event_name == 'release' || inputs.release_tag != ''
        uses: php/pie-ext-binary-builder@5298761950f63c7e9565ed7004e922b346e4386c # 0.0.3
        with:
          release-tag: ${{ github.event.release.tag_name || inputs.release_tag }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          configure-flags: '--enable-clickhouse'

      # Blank-tag dispatch: compile on the real runner without uploading, so the
      # Step 9.5 pre-tag gate ("build jobs green") is meaningful for this lane too.
      - name: Build-only validation (blank-tag dispatch)
        if: github.event_name == 'workflow_dispatch' && inputs.release_tag == ''
        run: |
          phpize
          ./configure --enable-clickhouse
          if command -v nproc >/dev/null 2>&1; then
            jobs=$(nproc)
          else
            jobs=$(sysctl -n hw.ncpu)
          fi
          make -j"$jobs"
          php -n -d extension="$PWD/modules/clickhouse.so" -r '
            if (!extension_loaded("clickhouse") || !class_exists("ClickHouse")) {
              exit(1);
            }
          '

      # Second pass, this time against the artifact that was actually published.
      # The pre-upload gate is what prevents a bad binary shipping; this proves
      # the shipped bytes match.
      - name: Verify release binary compatibility
        env:
          COMPAT_MAXIMUM: ${{ matrix.platform.compat_maximum }}
          COMPAT_MODE: ${{ matrix.platform.compat_mode }}
          PACKAGE_PATH: ${{ steps.prebuilt.outputs.package-path }}
          UPLOADED: ${{ (github.event_name == 'release' || inputs.release_tag != '') && '1' || '' }}
        run: |
          set -euo pipefail
          binary="$PWD/modules/clickhouse.so"
          if [[ -n "$PACKAGE_PATH" ]]; then
            archive_dir="$RUNNER_TEMP/release-binary"
            mkdir -p "$archive_dir"
            unzip -q "$PACKAGE_PATH" clickhouse.so -d "$archive_dir"
            binary="$archive_dir/clickhouse.so"
          elif [[ -n "$UPLOADED" ]]; then
            # An upload ran but produced no package path: the action's output
            # name changed. Falling back to a local build here would silently
            # inspect something other than the published artifact.
            echo "prebuilt step produced no package-path; refusing to verify a local build" >&2
            exit 1
          fi
          checker="scripts/check-release-binary.sh"
          if [[ -x .release-tools/scripts/check-release-binary.sh ]]; then
            checker=".release-tools/scripts/check-release-binary.sh"
          fi
          "$checker" \
            "$COMPAT_MODE" \
            "$COMPAT_MAXIMUM" \
            "$binary"