Seamless integration of tox into GitHub Actions

3.5.0 · active · verified Mon Apr 13

tox-gh-actions is a `tox` plugin that provides seamless integration of your `tox` test environments with GitHub Actions, automatically detecting Python versions from your workflow matrix and setting up problem matchers. It is an actively maintained library with frequent releases to support new Python versions and address issues.

Warnings

breaking Version 3.0.0 introduced breaking changes for users upgrading from tox v3 to tox v4. tox-gh-actions v3.x is compatible with tox v4, while tox-gh-actions v2.x is for tox v3.
Fix: If you are using tox v4, ensure you are on tox-gh-actions v3.0.0 or later. If you are using tox v3, you must stick to tox-gh-actions v2.x.
gotcha When using `tox`'s `requires` configuration in your `tox.ini` file, ensure `tox-gh-actions` is explicitly listed to guarantee the plugin is loaded correctly.
Fix: Add `requires = tox-gh-actions` to your `tox.ini` file, usually at the top-level `[tox]` section or within specific environment configurations if needed.
gotcha Early 3.1.x releases (3.1.0, 3.1.1, 3.1.2) had issues with `tox -p` (parallel execution) which could lead to `TypeError` or incorrect warning messages. These were resolved in subsequent patch releases.
Fix: Upgrade to `tox-gh-actions` v3.1.3 or later to ensure stable behavior with parallel `tox` execution (`tox -p`).

Install

pip install tox-gh-actions Install `tox-gh-actions`

Imports

tox-gh-actions
```
Install `tox-gh-actions` alongside `tox`. It is automatically loaded by `tox`.
```
As a `tox` plugin, `tox-gh-actions` is not typically imported directly in user Python code. It extends `tox`'s functionality via its entry points.

Quickstart

This GitHub Actions workflow demonstrates how to use `tox-gh-actions`. It sets up a matrix of Python versions, installs `tox` and `tox-gh-actions`, and then simply runs `tox`. The plugin automatically detects the Python version from the `python-version` matrix variable and maps it to the appropriate `tox` environment.

name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.8", "3.9", "3.10", "3.11"]

    steps:
    - uses: actions/checkout@v4
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install tox tox-gh-actions
    - name: Run tox
      run: tox

view raw JSON →