ci.yml

name: CI
on: [push, pull_request]
defaults:
  run:
    shell: bash
env:
  # We fetch Windows script executable stubs when building Pex.
  _PEX_CACHE_WINDOWS_STUBS_DIR: ${{ github.workspace }}/.pex_dev/windows_stubs
  _PEX_FETCH_WINDOWS_STUBS_BEARER: ${{ secrets.GITHUB_TOKEN }}

  # These timeouts help with flaky CI / oversubscription issues.
  _PEX_HTTP_SERVER_TIMEOUT: 30
  _PEX_PEXPECT_TIMEOUT: 10

  # We cache files under here in Mac and Windows jobs.
  _PEX_TEST_DEV_ROOT: ${{ github.workspace }}/.pex_dev

  # We have integration tests that exercise `--scie` support and these can trigger downloads from
  # GitHub Releases that need elevated rate limit quota, which this gives.
  SCIENCE_AUTH_API_GITHUB_COM_BEARER: ${{ secrets.GITHUB_TOKEN }}

  # We have integration tests that exercise `--scie` support and these can trigger downloads from
  # GitHub Releases that can be slow which this timeout accounts for.
  SCIENCE_NET_TIMEOUT: 30.0

  _TEST_POS_ARGS: "--color --devpi --devpi-timeout 15.0 --shutdown-devpi -vvs"
concurrency:
  group: CI-${{ github.ref }}
  # Queue on all branches and tags, but only cancel overlapping PR burns.
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && !startsWith(github.ref, 'refs/tags/') }}
jobs:
  setup:
    name: Check GitHub Organization
    if: github.repository_owner == 'pex-tool'
    runs-on: ubuntu-slim
    steps:
      - name: Noop
        if: false
        run: |
          echo "This is a dummy step that will never run."
  checks:
    name: "Unix: uv run dev-cmd ci-checks"
    needs: setup
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout Pex
        uses: actions/checkout@v4
        with:
          # We need branches and tags since package leans on `git describe`. Passing 0 gets us
          # complete history.
          fetch-depth: 0
      - name: Setup Python 3.9
        uses: actions/setup-python@v5
        with:
          # We need to keep Python 3.9 for consistent vendoring.
          python-version: "3.9"
      - name: Setup Python 3.11
        uses: actions/setup-python@v5
        with:
          # We use 3.11 for typecheck.
          python-version: "3.11"
      - name: Install uv
        uses: astral-sh/setup-uv@v5
      - name: Check Formatting, Lints and Types
        run: uv run dev-cmd -t format-check lint-check requires-python-check typecheck
      - name: Check Enum Types
        run: |
          BASE_MODE=pull ./duvrc.sh enum-check -- -v --require-py27
      - name: Check Vendoring
        run: uv run dev-cmd vendor-check
      - name: Check Packaging
        run: |
          uv run dev-cmd package -- \
            --additional-format sdist \
            --additional-format whl \
            --additional-format whl-3.12-plus \
            --embed-docs \
            --clean-docs \
            --scies \
            --gen-md-table-of-hash-and-size dist/hashes.md
      - name: Check Docs
        run: uv run dev-cmd docs -- --linkcheck --pdf --clean-html

  # N.B.: The name of this job key (linux-tests) is depended on by scripts/build_cache_image.py. In
  # particular, the test-cmd matrix list is used to ensure the cache covers all Linux CI jobs.
  linux-tests:
    name: "Linux: ./duvrc.sh ${{ matrix.test-cmd }} ${{ matrix.pex-test-pos-args }}"
    needs: setup
    runs-on: ubuntu-24.04
    strategy:
      matrix:
        include:
          # N.B.: When editing these, also edit build-cache-image.yml.

          # Unit tests:
          # -----------
          - test-cmd: test-py27-pip20.3.4--patched
          - test-cmd: test-py314-pip26.0.1
          - test-cmd: test-py315-pip26.0.1
          - test-cmd: test-pypy311-pip24.3.1

          # Integration tests, split most into two shards:
          # ----------------------------------------------

          # CPython 2.7 is fast enough not to require sharding.
          - test-cmd: test-py27-pip20.3.4--patched-integration

          - test-cmd: test-py38-pip22.3.1-integration
            pex-test-pos-args: --shard 1/2
          - test-cmd: test-py38-pip22.3.1-integration
            pex-test-pos-args: --shard 2/2

          - test-cmd: test-py314-pip26.0.1-integration
            pex-test-pos-args: --shard 1/2
          - test-cmd: test-py314-pip26.0.1-integration
            pex-test-pos-args: --shard 2/2

          - test-cmd: test-py315-pip26.0.1-integration
            pex-test-pos-args: --shard 1/2
          - test-cmd: test-py315-pip26.0.1-integration
            pex-test-pos-args: --shard 2/2

          # PyPy is slow enough to require extra sharding.
          - test-cmd: test-pypy311-pip24.3.1-integration
            pex-test-pos-args: --shard 1/4
          - test-cmd: test-pypy311-pip24.3.1-integration
            pex-test-pos-args: --shard 2/4
          - test-cmd: test-pypy311-pip24.3.1-integration
            pex-test-pos-args: --shard 3/4
          - test-cmd: test-pypy311-pip24.3.1-integration
            pex-test-pos-args: --shard 4/4
    steps:
      - name: Free Up Disk Space
        uses: jlumbroso/free-disk-space@v1.3.1
        with:
          android: true # ~14GB
          dotnet: true # ~2GB
          tool-cache: true # ~12GB

          # Too little space savings or too slow.
          haskell: false
          large-packages: false
          docker-images: false
          swap-storage: false
      - name: Checkout Pex
        uses: actions/checkout@v4
        with:
          # We need branches and tags for some ITs.
          fetch-depth: 0
      # Some ITs need this for VCS URLs of the form git+ssh://git@github.com/...
      - name: Setup SSH Agent
        uses: webfactory/ssh-agent@v0.9.0
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
        if: env.SSH_PRIVATE_KEY != ''
        with:
          ssh-private-key: ${{ env.SSH_PRIVATE_KEY }}
      - name: Run Tests
        run: |
          # This is needed to get pexpect tests working under PyPy running under docker.
          export TERM="xterm"

          # The image uses its own internal settings for these.          
          unset _PEX_CACHE_WINDOWS_STUBS_DIR
          unset _PEX_TEST_DEV_ROOT

          BASE_MODE=pull CACHE_MODE=pull \
            ./duvrc.sh ${{ matrix.test-cmd }} -- \
              ${{ env._TEST_POS_ARGS }} ${{ matrix.pex-test-pos-args }}
  mac-tests:
    name: "Mac: uv run dev-cmd ${{ matrix.test-cmd }} ${{ matrix.pex-test-pos-args }}"
    needs: setup
    runs-on: macos-15
    strategy:
      matrix:
        include:
          - python-version: "3.14"
            test-cmd: test-py314-pip26.0.1
          - python-version: "3.14"
            test-cmd: test-py314-pip26.0.1-integration
            pex-test-pos-args: --shard 1/2
          - python-version: "3.14"
            test-cmd: test-py314-pip26.0.1-integration
            pex-test-pos-args: --shard 2/2
    steps:
      - name: Checkout Pex
        uses: actions/checkout@v4
        with:
          # We need branches and tags for some ITs.
          fetch-depth: 0
          path: repo
      - name: Setup Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: "${{ matrix.python-version }}"
      - name: Expose Pythons
        uses: pex-tool/actions/expose-pythons@e22fe0e0fe85e1f7eb5bbfc7674c7cbbf24ae6b5
      - name: Restore Cached Pyenv Interpreters
        id: restore-pyenv-interpreters
        uses: actions/cache/restore@v4
        with:
          path: ${{ env._PEX_TEST_DEV_ROOT }}/pyenv
          key: macos-15-${{ runner.arch }}-pex-test-dev-root-pyenv-v1
      - name: Restore Cached Devpi Server
        id: restore-devpi-server
        uses: actions/cache/restore@v4
        with:
          path: ${{ env._PEX_TEST_DEV_ROOT }}/devpi
          # We're using a key suffix / restore-keys prefix trick here to get an updatable cache.
          # See: https://github.com/actions/cache/blob/main/tips-and-workarounds.md#update-a-cache
          key: macos-15-${{ runner.arch }}-${{ matrix.test-cmd }}-pex-test-dev-root-devpi-v2-${{ github.run_id }}
          restore-keys: macos-15-${{ runner.arch }}-${{ matrix.test-cmd }}-pex-test-dev-root-devpi-v2
      - name: Restore Windows Stubs
        id: restore-windows-stubs
        uses: actions/cache/restore@v4
        with:
          path: ${{ env._PEX_CACHE_WINDOWS_STUBS_DIR }}
          key: macos-15-${{ runner.arch }}-pex-cache-windows-stubs-dir-v1
      # Some ITs need this for VCS URLs of the form git+ssh://git@github.com/...
      - name: Setup SSH Agent
        uses: webfactory/ssh-agent@v0.9.0
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
        if: env.SSH_PRIVATE_KEY != ''
        with:
          ssh-private-key: ${{ env.SSH_PRIVATE_KEY }}
      - name: Install uv
        uses: astral-sh/setup-uv@v5
      - name: Run Tests
        run: |
          cd repo
          uv run dev-cmd ${{ matrix.test-cmd }} -- \
            ${{ env._TEST_POS_ARGS }} ${{ matrix.pex-test-pos-args }}
      - name: Cache Pyenv Interpreters
        uses: actions/cache/save@v4
        if: github.ref == 'refs/heads/main'
        with:
          path: ${{ env._PEX_TEST_DEV_ROOT }}/pyenv
          key: ${{ steps.restore-pyenv-interpreters.outputs.cache-primary-key }}
      - name: Cache Devpi Server
        uses: actions/cache/save@v4
        if: github.ref == 'refs/heads/main'
        with:
          path: ${{ env._PEX_TEST_DEV_ROOT }}/devpi
          key: ${{ steps.restore-devpi-server.outputs.cache-primary-key }}
      - name: Cache Windows Stubs
        uses: actions/cache/save@v4
        if: github.ref == 'refs/heads/main'
        with:
          path: ${{ env._PEX_CACHE_WINDOWS_STUBS_DIR }}
          key: ${{ steps.restore-windows-stubs.outputs.cache-primary-key }}
  windows-tests:
    name: "Windows: uv run dev-cmd ${{ matrix.test-cmd }} ${{ matrix.pex-test-pos-args }}"
    needs: setup
    runs-on: windows-2022
    continue-on-error: true
    strategy:
      matrix:
        include:
          # N.B.: We use 3.11 to work around issues building typed-ast for the typecheck step.
          # There is a Windows wheel for CPython 3.11, but no higher CPython version.
          #
          # N.B.: The `-o junit_logging=no` option used in the test shards ensures test stdout /
          # stderr do not make it in junit xml artifacts. Env var secrets can leak this way when
          # subprocess launches fail and env vars are logged. We only need the success / fail counts
          # for the overall Windows bring-up project health report.
          - python-version: "3.11"
            test-cmd: typecheck package docs
          - python-version: "3.14"
            test-cmd: test-py314-pip26.0.1
            artifact-name: unit
            pex-test-pos-args: --junit-report ../dist/test-results/unit.xml
          - python-version: "3.14"
            test-cmd: test-py314-pip26.0.1-integration
            artifact-name: integration-1
            pex-test-pos-args: --shard 1/3 --junit-report ../dist/test-results/integration-1.xml
          - python-version: "3.14"
            test-cmd: test-py314-pip26.0.1-integration
            artifact-name: integration-2
            pex-test-pos-args: --shard 2/3 --junit-report ../dist/test-results/integration-2.xml
          - python-version: "3.14"
            test-cmd: test-py314-pip26.0.1-integration
            artifact-name: integration-3
            pex-test-pos-args: --shard 3/3 --junit-report ../dist/test-results/integration-3.xml
    steps:
      - name: Checkout Pex
        uses: actions/checkout@v4
        with:
          # We need branches and tags for some ITs.
          fetch-depth: 0
          path: repo
      - name: Setup Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: "${{ matrix.python-version }}"
      - name: Install uv
        uses: astral-sh/setup-uv@v5
      - name: Restore Cached Devpi Server
        id: restore-devpi-server
        uses: actions/cache/restore@v4
        with:
          path: ${{ env._PEX_TEST_DEV_ROOT }}/devpi
          # We're using a key suffix / restore-keys prefix trick here to get an updatable cache.
          # See: https://github.com/actions/cache/blob/main/tips-and-workarounds.md#update-a-cache
          key: windows-2022-${{ runner.arch }}-${{ matrix.test-cmd }}-pex-test-dev-root-devpi-v2-${{ github.run_id }}
          restore-keys: windows-2022-${{ runner.arch }}-${{ matrix.test-cmd }}-pex-test-dev-root-devpi-v2
      - name: Restore Windows Stubs
        id: restore-windows-stubs
        uses: actions/cache/restore@v4
        with:
          path: ${{ env._PEX_CACHE_WINDOWS_STUBS_DIR }}
          key: windows-2022-${{ runner.arch }}-pex-cache-windows-stubs-dir-v1
      # Some ITs need this for VCS URLs of the form git+ssh://git@github.com/...
      - name: Setup SSH Agent
        uses: webfactory/ssh-agent@v0.9.0
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
        if: env.SSH_PRIVATE_KEY != ''
        with:
          ssh-private-key: ${{ env.SSH_PRIVATE_KEY }}
      - name: Install OpenSSL (Windows)
        shell: powershell
        run: |
          echo "VCPKG_ROOT=$env:VCPKG_INSTALLATION_ROOT" | Out-File -FilePath $env:GITHUB_ENV -Append
          vcpkg install openssl:x64-windows-static-md
      - name: Run Tests
        if: ${{ ! matrix.pex-test-pos-args }}
        continue-on-error: true
        run: |
          cd repo
          uv run dev-cmd ${{ matrix.test-cmd }}
      - name: Run Tests
        if: ${{ matrix.pex-test-pos-args }}
        continue-on-error: true
        run: |
          cd repo
          uv run dev-cmd ${{ matrix.test-cmd }} -- \
          ${{ env._TEST_POS_ARGS }} \
          ${{ matrix.pex-test-pos-args }} \
          --junit-report-suppress-stdio \
          --junit-report-redact "${{ secrets.GITHUB_TOKEN }}" \
          --junit-report-redact "${{ secrets.SSH_PRIVATE_KEY }}"
      - uses: actions/upload-artifact@v4
        if: always() && matrix.artifact-name
        with:
          name: test-results-${{ matrix.artifact-name }}
          path: |
            dist/test-results/
            .gitignore
      - name: Cache Devpi Server
        uses: actions/cache/save@v4
        if: github.ref == 'refs/heads/main'
        with:
          path: ${{ env._PEX_TEST_DEV_ROOT }}/devpi
          key: ${{ steps.restore-devpi-server.outputs.cache-primary-key }}
      - name: Cache Windows Stubs
        uses: actions/cache/save@v4
        if: github.ref == 'refs/heads/main'
        with:
          path: ${{ env._PEX_CACHE_WINDOWS_STUBS_DIR }}
          key: ${{ steps.restore-windows-stubs.outputs.cache-primary-key }}
  windows-reports:
    name: Consolidate Windows Test Results
    needs: windows-tests
    if: always()
    runs-on: ubuntu-slim
    steps:
      - uses: actions/download-artifact@v4
        with:
          merge-multiple: true
      - uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: |
            dist/test-results/
            .gitignore
  final-status:
    name: Gather Final Status
    needs:
      - checks
      - linux-tests
      - mac-tests
      - windows-reports
    runs-on: ubuntu-24.04
    steps:
      - name: Check Non-Success
        if: |
          contains(needs.*.result, 'cancelled') ||
          contains(needs.*.result, 'failure') ||
          contains(needs.*.result, 'skipped')
        run: "false"
      - name: Success
        run: "true"