check workflow (tox-dev/platformdirs)

The check workflow from tox-dev/platformdirs, explained and optimized by Latchkey.

CI health: A - excellent

Point runs-on at Latchkey and get job timeouts, self-healing for flaky steps, and up to 58% lower cost, applied automatically.

Grade your own workflow free or run it on Latchkey →

Source: tox-dev/platformdirs.github/workflows/check.yamlLicense MITView source

What it does

This is the check workflow from the tox-dev/platformdirs repository, a real project running GitHub Actions. It is shown here with attribution under its MIT license.

Below, Latchkey shows a faster, safer version produced by its optimization engine.

The workflow

workflow (.yml)

name: check
on:
  workflow_dispatch:
  push:
    branches: ["main"]
    tags-ignore: ["**"]
  pull_request:
  schedule:
    - cron: "0 8 * * *"
concurrency:
  group: check-${{ github.ref }}
  cancel-in-progress: true
permissions:
  contents: read
jobs:
  test:
    name: test ${{ matrix.py }} - ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        py:
          - "pypy3.11"
          - "3.14"
          - "3.13"
          - "3.12"
          - "3.11"
          - "3.10"
        os:
          - ubuntu-24.04
          - windows-2025
          - macos-15
        exclude:
          - {os: windows-2025, py: pypy3.11}
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: false
      - name: Install tox
        run: uv tool install --python-preference only-managed --python 3.14 tox --with tox-uv
      - name: Install Python
        run: uv python install --python-preference only-managed ${{ matrix.py }}
      - name: Setup test suite
        run: tox run -vv --notest --skip-missing-interpreters false -e ${{ matrix.py }}
        env:
          UV_PYTHON_PREFERENCE: only-managed
      - name: Run test suite
        run: |
          if [[ "${{ matrix.py }}" == pypy* ]]; then
            tox run --skip-pkg-install -e ${{ matrix.py }} --
          else
            tox run --skip-pkg-install -e ${{ matrix.py }}
          fi
        shell: bash
        env:
          PYTEST_ADDOPTS: "-vv --durations=20"
          UV_PYTHON_PREFERENCE: only-managed
          DIFF_AGAINST: HEAD
      - name: Rename coverage report file
        if: ${{ !startsWith(matrix.py, 'pypy')}}
        run: |
          import os; import sys
          os.rename(f".tox/.coverage.${{ matrix.py }}", f".tox/.coverage.${{ matrix.py }}-{sys.platform}")
        shell: python
      - name: Upload coverage data
        if: ${{ !startsWith(matrix.py, 'pypy')}}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          include-hidden-files: true
          name: .coverage.${{ matrix.os }}.${{ matrix.py }}
          path: ".tox/.coverage.*"
          retention-days: 3
  coverage:
    name: Combine coverage
    runs-on: ubuntu-24.04
    needs: test
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: false
      - name: Install tox
        run: uv tool install --python-preference only-managed --python 3.14 tox --with tox-uv
      - name: Build package to generate version
        run: uv build --python 3.14 --python-preference only-managed --wheel . --out-dir dist
      - name: Setup coverage tool
        run: tox -e coverage --notest
        env:
          UV_PYTHON_PREFERENCE: only-managed
      - name: Download coverage data
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
        with:
          path: .tox
          pattern: .coverage.*
          merge-multiple: true
      - name: Combine and report coverage
        run: tox -e coverage --skip-pkg-install
        env:
          UV_PYTHON_PREFERENCE: only-managed
      - name: Upload HTML report
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: html-report
          path: .tox/htmlcov
  check:
    name: ${{ matrix.tox_env }} - ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os:
          - ubuntu-24.04
          - windows-2025
        tox_env:
          - dev
          - type
          - docs
          - pkg_meta
        exclude:
          - {os: windows-2025, tox_env: pkg_meta}
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: false
      - name: Install tox
        run: uv tool install --python-preference only-managed --python 3.14 tox --with tox-uv
      - name: Setup test suite
        run: tox run -vv --notest --skip-missing-interpreters false -e ${{ matrix.tox_env }}
        env:
          UV_PYTHON_PREFERENCE: only-managed
      - name: Run test suite
        run: tox run --skip-pkg-install -e ${{ matrix.tox_env }}
        env:
          UV_PYTHON_PREFERENCE: only-managed

The same workflow, on Latchkey

Removes redundant runs and caps runaway jobs. Added and changed lines are highlighted.

name: check
on:
  workflow_dispatch:
  push:
    branches: ["main"]
    tags-ignore: ["**"]
  pull_request:
  schedule:
    - cron: "0 8 * * *"
concurrency:
  group: check-${{ github.ref }}
  cancel-in-progress: true
permissions:
  contents: read
jobs:
  test:
    timeout-minutes: 30
    name: test ${{ matrix.py }} - ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        py:
          - "pypy3.11"
          - "3.14"
          - "3.13"
          - "3.12"
          - "3.11"
          - "3.10"
        os:
          - ubuntu-24.04
          - windows-2025
          - macos-15
        exclude:
          - {os: windows-2025, py: pypy3.11}
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: false
      - name: Install tox
        run: uv tool install --python-preference only-managed --python 3.14 tox --with tox-uv
      - name: Install Python
        run: uv python install --python-preference only-managed ${{ matrix.py }}
      - name: Setup test suite
        run: tox run -vv --notest --skip-missing-interpreters false -e ${{ matrix.py }}
        env:
          UV_PYTHON_PREFERENCE: only-managed
      - name: Run test suite
        run: |
          if [[ "${{ matrix.py }}" == pypy* ]]; then
            tox run --skip-pkg-install -e ${{ matrix.py }} --
          else
            tox run --skip-pkg-install -e ${{ matrix.py }}
          fi
        shell: bash
        env:
          PYTEST_ADDOPTS: "-vv --durations=20"
          UV_PYTHON_PREFERENCE: only-managed
          DIFF_AGAINST: HEAD
      - name: Rename coverage report file
        if: ${{ !startsWith(matrix.py, 'pypy')}}
        run: |
          import os; import sys
          os.rename(f".tox/.coverage.${{ matrix.py }}", f".tox/.coverage.${{ matrix.py }}-{sys.platform}")
        shell: python
      - name: Upload coverage data
        if: ${{ !startsWith(matrix.py, 'pypy')}}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          include-hidden-files: true
          name: .coverage.${{ matrix.os }}.${{ matrix.py }}
          path: ".tox/.coverage.*"
          retention-days: 3
  coverage:
    timeout-minutes: 30
    name: Combine coverage
    runs-on: latchkey-small
    needs: test
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: false
      - name: Install tox
        run: uv tool install --python-preference only-managed --python 3.14 tox --with tox-uv
      - name: Build package to generate version
        run: uv build --python 3.14 --python-preference only-managed --wheel . --out-dir dist
      - name: Setup coverage tool
        run: tox -e coverage --notest
        env:
          UV_PYTHON_PREFERENCE: only-managed
      - name: Download coverage data
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
        with:
          path: .tox
          pattern: .coverage.*
          merge-multiple: true
      - name: Combine and report coverage
        run: tox -e coverage --skip-pkg-install
        env:
          UV_PYTHON_PREFERENCE: only-managed
      - name: Upload HTML report
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: html-report
          path: .tox/htmlcov
  check:
    timeout-minutes: 30
    name: ${{ matrix.tox_env }} - ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os:
          - ubuntu-24.04
          - windows-2025
        tox_env:
          - dev
          - type
          - docs
          - pkg_meta
        exclude:
          - {os: windows-2025, tox_env: pkg_meta}
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
        with:
          enable-cache: false
      - name: Install tox
        run: uv tool install --python-preference only-managed --python 3.14 tox --with tox-uv
      - name: Setup test suite
        run: tox run -vv --notest --skip-missing-interpreters false -e ${{ matrix.tox_env }}
        env:
          UV_PYTHON_PREFERENCE: only-managed
      - name: Run test suite
        run: tox run --skip-pkg-install -e ${{ matrix.tox_env }}
        env:
          UV_PYTHON_PREFERENCE: only-managed

What changed

Run on Latchkey managed runners with one line (runs-on), which apply the fixes below automatically and self-heal transient failures. This example uses latchkey-small; pick the runner size that fits the job.
Add a job timeout so a hung step cannot burn hours of runner time.

This workflow runs 3 jobs (27 with the matrix expanded) per trigger. On Latchkey the same minutes cost up to 58% less than GitHub-hosted, with zero queue time.

Actions used in this workflow

actions/checkout astral-sh/setup-uv actions/upload-artifact actions/download-artifact