tox-gh is a tox plugin, which helps run tox on GitHub Actions with multiple different Python versions on multiple workers in parallel.
When running tox on GitHub Actions, tox-gh:
- detects which environment to run based on configurations (or bypasses detection and sets it explicitly via the
TOX_GH_MAJOR_MINOR
environment variable), - provides utilities such as grouping log lines.
- Add configurations under
[gh]
section along with your tox configuration. - Install
tox-gh
package in the GitHub Actions workflow before runningtox
command.
Add [gh]
section to the same file as tox configuration.
If you're using tox.ini
:
[gh] python = 3.14t = 3.14t 3.14 = 3.14, type, dev, pkg_meta 3.13 = 3.13 3.12 = 3.12
For tox.toml
:
[gh.python] "3.14t" = ["3.14t"] "3.14" = ["3.14", "type", "pkg_meta"] "3.13" = ["3.13"] "3.12" = ["3.12"]
For pyproject.toml
:
[tool.tox.gh.python] "3.14t" = ["3.14t"] "3.14" = ["3.14", "type", "pkg_meta"] "3.13" = ["3.13"] "3.12" = ["3.12"]
This will run a different set of tox environments on different Python versions set up via GitHub setup-python
action:
- on Python 3.14t job, tox runs
3.14t
environment, - on Python 3.14 job, tox runs
3.14
,type
andpkg_meta
environments, - on Python 3.13 job, tox runs
3.13
environment, - on Python 3.12 job, tox runs
3.12
environment,
A bare-bones example would be .github/workflows/check.yaml
:
jobs: test: name: test with ${{ matrix.env }} on ${{ matrix.os }} runs-on: ${{ matrix.os }} strategy: fail-fast: false matrix: env: - "3.14t" - "3.14" - "3.13" os: - ubuntu-latest - macos-latest steps: - uses: actions/checkout@v5 - name: Install the latest version of uv uses: astral-sh/setup-uv@v7 - name: Install tox run: uv tool install --python-preference only-managed --python 3.14 tox --with tox-uv --with tox-gh - name: Install Python if: matrix.env != '3.14' run: uv python install --python-preference only-managed ${{ matrix.env }} - name: Setup test suite run: tox run -vv --notest --skip-missing-interpreters false env: TOX_GH_MAJOR_MINOR: ${{ matrix.env }} - name: Run test suite run: tox run --skip-pkg-install env: TOX_GH_MAJOR_MINOR: ${{ matrix.env }}
A more exhaustive example would be .github/workflows/check.yaml
:
name: check on: workflow_dispatch: push: branches: ["main"] tags-ignore: ["**"] pull_request: schedule: # Runs at 8 AM every day - cron: "0 8 * * *" concurrency: group: check-${{ github.ref }} cancel-in-progress: true jobs: test: name: test with ${{ matrix.env }} on ${{ matrix.os }} runs-on: ${{ matrix.os }} strategy: fail-fast: false matrix: env: - "3.14t" - "3.14" - "3.13" os: - ubuntu-latest - macos-latest - windows-latest steps: - uses: actions/checkout@v5 with: fetch-depth: 0 - name: Install the latest version of uv uses: astral-sh/setup-uv@v7 with: enable-cache: true cache-dependency-glob: "pyproject.toml" github-token: ${{ secrets.GITHUB_TOKEN }} - name: Add .local/bin to Windows PATH if: runner.os == 'Windows' shell: bash run: echo "$USERPROFILE/.local/bin" >> $GITHUB_PATH - name: Install tox run: uv tool install --python-preference only-managed --python 3.14 tox --with tox-uv --with tox-gh - name: Install Python if: matrix.env != '3.14' run: uv python install --python-preference only-managed ${{ matrix.env }} - name: Setup test suite run: tox run -vv --notest --skip-missing-interpreters false env: TOX_GH_MAJOR_MINOR: ${{ matrix.env }} - name: Run test suite run: tox run --skip-pkg-install env: TOX_GH_MAJOR_MINOR: ${{ matrix.env }}
- When a list of environments to run is specified explicitly via
-e
option orTOXENV
environment variabletox-gh
respects the given environments and simply runs the given environments without enforcing its configuration. - The plugin only activates if the environment variable
GITHUB_ACTIONS
istrue
.