Package: tox-gh-actions
tox-gh-actionstox-gh-actionsis a tox plugin which helps running tox on GitHub Actions
with multiple different Python versions on multiple workers in parallel.
This project is inspired bytox-travis.Versions and CompatibilityCurrently, tox-gh-actions supports both tox 3 and 4, but users need to install the appropriate version by following the table below.toxtox-gh-actionsSupported by tox-gh-actionsBranch4.x3.xYes (stable)master3.x2.xYes (stable)tox3FeaturesUsageExamplesBasic Exampletox-gh-actions ConfigurationWorkflow ConfigurationAdvanced ExamplesFactor-Conditional Settings: Python VersionFactor-Conditional Settings: Environment Variabletox requiresOverriding Environments to RunVersioningUnderstanding Behavior of tox-gh-actionsHow tox-gh-actions WorksLoggingFeaturesWhen running tox on GitHub Actions, tox-gh-actionsdetects which environment to run based on configurations andprovides utilities such asgrouping log lines.UsageAdd configurations under[gh-actions]section along with tox's configuration.It will bepyproject.toml,tox.ini, orsetup.cfg. Seetox's documentationfor more details.Installtox-gh-actionspackage in the GitHub Actions workflow before runningtoxcommand.ExamplesBasic ExampleThe following configuration will create 4 jobs when running the workflow on GitHub Actions.On Python 3.7 job, tox runspy37environmentOn Python 3.8 job, tox runspy38environmentOn Python 3.9 job, tox runspy39environmentOn Python 3.10 job, tox runspy310andmypyenvironmentstox-gh-actions ConfigurationAdd[gh-actions]section to the same file as tox's configuration.If you're usingtox.ini:[tox]envlist=py37, py38, py39, py310, mypy[gh-actions]python=3.7:py373.8:py383.9:py393.10:py310, mypy[testenv]...If you're usingsetup.cfg:[tox:tox]envlist=py37, py38, py39, py310, mypy[gh-actions]python=3.7:py373.8:py383.9:py393.10:py310, mypy[testenv]...If you're usingpyproject.toml:[tool.tox]legacy_tox_ini="""[tox]envlist = py37, py38, py39, py310, mypy[gh-actions]python =3.7: py373.8: py383.9: py393.10: py310, mypy[testenv]"""Workflow Configuration.github/workflows/<workflow>.yml:name:Python packageon:-push-pull_requestjobs:build:runs-on:ubuntu-lateststrategy: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@v4with:python-version:${{ matrix.python-version }}-name:Install dependenciesrun:|python -m pip install --upgrade pippython -m pip install tox tox-gh-actions-name:Test with toxrun:toxAdvanced ExamplesFactor-Conditional Settings: Python VersionThe following configuration will create 2 jobs when running the workflow on GitHub Actions.On Python 3.7 job, tox runspy37-django22andpy37-django32environmentsOn Python 3.8 job, tox runspy38-django32environmenttox.ini:[tox]envlist=py37-django{22,32}, py38-django32[gh-actions]python=3.7:py373.8:py38[testenv]...When using pre-release versions of Python, please do not specify-betaor-devintox.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:py393.10:py310# The following won't work# 3.10-beta.3: py310# 3.10-dev: py310[testenv]...PyPy is also supported in thepythonconfiguration 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:py373.8:py38, mypypypy-3.7:pypy3pyston-3.8:pyston38[testenv]...[testenv:pyston38]basepython=pyston38You can also specify without minor versions in thepythonconfiguration key.tox.ini:[tox]envlist=py3, pypy3[gh-actions]python=3:py3, mypypypy-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 andgh-actions.pythonhas both3and3.8,
tox-gh-actions gets factors only from the key3.8.Changed in 3.0:pypy3is not supported in the configuration anymore. Please usepypy-3instead.Factor-Conditional Settings: Environment VariableYou 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.On Python 3.8/ubuntu-latest job, tox runspy38-linuxenvironmentOn Python 3.9/ubuntu-latest job, tox runspy39-linuxenvironmentand so on..github/workflows/<workflow>.yml:name:Python packageon:-push-pull_requestjobs: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@v4with:python-version:${{ matrix.python-version }}-name:Install dependenciesrun:|python -m pip install --upgrade pippython -m pip install tox tox-gh-actions-name:Test with toxrun:toxenv:PLATFORM:${{ matrix.platform }}tox.ini:[tox]envlist=py{38,39,310}-{linux,macos,windows}[gh-actions]python=3.8:py383.9:py393.10:py310[gh-actions:env]PLATFORM=ubuntu-latest:linuxmacos-latest:macoswindows-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.tox requiresIf your project usestox'srequiresconfiguration,
you must add tox-gh-actionsto therequires` configuration as well. Otherwise, tox-gh-actions won't be loaded as a tox plugin.[tox]requires=tox-condatox-gh-actionsOverriding Environments to RunChanged in 2.0: When a list of environments to run is specified explicitly via-eoption orTOXENVenvironment 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.VersioningThis project followsPEP 440and 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.Understanding Behavior of tox-gh-actionsHow tox-gh-actions WorksSeeARCHITECTURE.mdfor more details.Loggingtox-gh-actions writes log messages using the standardloggingmodule.
This is handy for understanding behavior of tox-gh-actions and for debugging tox-gh-actions.
To see the log messages, please runtox -vv.