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 bypass detection and set 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.13 = 3.13, type, dev, pkg_meta
3.12 = 3.12
3.11 = 3.11
For tox.toml
:
[gh.python]
"3.13" = ["3.13", "type", "pkg_meta"]
"3.12" = ["3.12"]
"3.11" = ["3.11"]
For pyproject.toml
:
[tool.tox.gh.python]
"3.13" = ["3.13", "type", "pkg_meta"]
"3.12" = ["3.12"]
"3.11" = ["3.11"]
This will run a different set of tox environments on different python versions set up via GitHub setup-python
action:
- on Python 3.13 job, tox runs
3.13
,type
andpkg_meta
environment, - on Python 3.12 job, tox runs
3.12
environment, - on Python 3.11 job, tox runs
3.11
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.13"
- "3.12"
os:
- ubuntu-latest
- macos-latest
steps:
- uses: actions/checkout@v4
- name: Install the latest version of uv
uses: astral-sh/setup-uv@v3
- name: Install tox
run: uv tool install --python-preference only-managed --python 3.13 tox --with tox-uv --with tox-gh
- name: Install Python
if: matrix.env != '3.13'
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:
- 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.13"
- "3.12"
- "3.11"
os:
- ubuntu-latest
- macos-latest
- windows-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install the latest version of uv
uses: astral-sh/setup-uv@v3
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.13 tox --with tox-uv --with tox-gh
- name: Install Python
if: matrix.env != '3.13'
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
.