Seamless integration of tox into GitHub Actions
tox-gh-actions is a tox plugin which helps running tox on GitHub Actions with multiple different Python versions on multiple workers in parallel. This project is inspired by tox-travis.
Currently, tox-gh-actions supports both tox 3 and 4, but users need to install the appropriate version by following the table below.
tox | tox-gh-actions | Supported by tox-gh-actions | Branch |
---|---|---|---|
4.x | 3.x | Yes (stable) | master |
3.x | 2.x | Yes (stable) | tox3 |
When running tox on GitHub Actions, tox-gh-actions
Add configurations under [gh-actions]
section along with tox's configuration.
pyproject.toml
, tox.ini
, or setup.cfg
. See tox's documentation for more details.Install tox-gh-actions
package in the GitHub Actions workflow before running tox
command.
The following configuration will create 4 jobs when running the workflow on GitHub Actions.
py37
environmentpy38
environmentpy39
environmentpy310
and mypy
environmentsAdd [gh-actions]
section to the same file as tox's configuration.
If you're using tox.ini
:
[tox]
envlist = py37, py38, py39, py310, mypy
[gh-actions]
python =
3.7: py37
3.8: py38
3.9: py39
3.10: py310, mypy
[testenv]
...
If you're using setup.cfg
:
[tox:tox]
envlist = py37, py38, py39, py310, mypy
[gh-actions]
python =
3.7: py37
3.8: py38
3.9: py39
3.10: py310, mypy
[testenv]
...
If you're using pyproject.toml
:
[tool.tox]
legacy_tox_ini = """
[tox]
envlist = py37, py38, py39, py310, mypy
[gh-actions]
python =
3.7: py37
3.8: py38
3.9: py39
3.10: py310, mypy
[testenv]
"""
.github/workflows/<workflow>.yml
:
name: Python package
on:
- push
- pull_request
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ['3.7', '3.8', '3.9', '3.10']
steps:
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install tox tox-gh-actions
- name: Test with tox
run: tox
The following configuration will create 2 jobs when running the workflow on GitHub Actions.
py37-django22
and py37-django32
environmentspy38-django32
environmenttox.ini
:
[tox]
envlist = py37-django{22,32}, py38-django32
[gh-actions]
python =
3.7: py37
3.8: py38
[testenv]
...
When using pre-release versions of Python, please do not specify -beta
or -dev
in tox.ini
.
.github/workflows/<workflow>.yml
:
...
jobs:
build:
strategy:
matrix:
python-version: [3.9, 3.10.0-beta.3]
...
tox.ini
:
[tox]
envlist = py39, py310
[gh-actions]
python =
3.9: py39
3.10: py310
# The following won't work
# 3.10-beta.3: py310
# 3.10-dev: py310
[testenv]
...
PyPy is also supported in the python
configuration key.
Support of Pyston is experimental and not tested by our CI.
tox.ini
:
[tox]
envlist = py37, py38, pypy3, pyston38
[gh-actions]
python =
3.7: py37
3.8: py38, mypy
pypy-3.7: pypy3
pyston-3.8: pyston38
[testenv]
...
[testenv:pyston38]
basepython = pyston38
You can also specify without minor versions in the python
configuration key.
tox.ini
:
[tox]
envlist = py3, pypy3
[gh-actions]
python =
3: py3, mypy
pypy-3: pypy3
[testenv]
...
If there are multiple matching Python versions in the configuration, only the most precise one is used.
For example, if you are running CPython 3.8 and gh-actions.python
has both 3
and 3.8
,
tox-gh-actions gets factors only from the key 3.8
.
Changed in 3.0: pypy3
is not supported in the configuration anymore. Please use pypy-3
instead.
You can also use environment variable to decide which environment to run. The following is an example to install different dependency based on platform. It will create 9 jobs when running the workflow on GitHub Actions.
py38-linux
environmentpy39-linux
environment.github/workflows/<workflow>.yml
:
name: Python package
on:
- push
- pull_request
jobs:
build:
runs-on: ${{ matrix.platform }}
strategy:
matrix:
platform: [ubuntu-latest, macos-latest, windows-latest]
python-version: ['3.8', '3.9', '3.10']
steps:
- uses: actions/checkout@v3
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install tox tox-gh-actions
- name: Test with tox
run: tox
env:
PLATFORM: ${{ matrix.platform }}
tox.ini
:
[tox]
envlist = py{38,39,310}-{linux,macos,windows}
[gh-actions]
python =
3.8: py38
3.9: py39
3.10: py310
[gh-actions:env]
PLATFORM =
ubuntu-latest: linux
macos-latest: macos
windows-latest: windows
[testenv]
deps =
<common dependency>
linux: <Linux specific deps>
macos: <macOS specific deps>
windows: <Windows specific deps>
...
Changed in 3.0: Environment variables should not use lowercase letters.
Because of the limitation in tox's configuration loading API,
tox-gh-actions always convert keys in [gh-actions:env]
to uppercase.
Changed in 2.0: When a list of environments to run is specified explicitly via -e
option or TOXENV
environment variable (tox's help),
tox-gh-actions respects the given environments and simply runs the given environments without enforcing its configuration.
Before 2.0, tox-gh-actions was always enforcing its configuration even when a list of environments is given explicitly.
This project follows PEP 440 and uses a format of major.minor.patch (X.Y.Z). The major version (X) will be incremented when we make backward incompatible changes to a public API. The public API of this project is the configuration of tox-gh-actions. The major version can be also incremented when we require a new version of tox.
This project tries not to introduce backward incompatibles changes as much as possible so that users don't need to update their project's configuration too frequently.
tox-gh-actions 3.x may drop support of unsupported Python 3.y versions in the future without bumping its major version.
See ARCHITECTURE.md for more details.
tox-gh-actions writes log messages using the standard logging
module.
This is handy for understanding behavior of tox-gh-actions and for debugging tox-gh-actions.
To see the log messages, please run tox -vv
.