tox-gh

1.7.1 verified Mon Apr 27 auth: no python

Seamless integration of tox into GitHub Actions. Automatically detects GitHub Actions environment variables for parallel tox execution and job summaries. Latest version: 1.7.1, requires Python >=3.10. Release cadence: irregular.

pip install tox-gh

Common errors

error tox-gh: GITHUB_ENV not set ↓

cause tox-gh is being run outside GitHub Actions (e.g., locally).

fix

Run only in GitHub Actions workflow; for local testing, remove tox-gh or set a dummy GITHUB_ENV variable.

error AttributeError: module 'tox' has no attribute 'plugins' ↓

cause Using an outdated version of tox that doesn't support the plugin system (tox <4.0).

fix

Upgrade tox to version >=4.0: pip install --upgrade tox>=4.0.

error Error: The `tox-gh` plugin is not compatible with this version of tox. Please update tox. ↓

cause Version mismatch between tox-gh and tox.

fix

Ensure both tox and tox-gh are up-to-date: pip install --upgrade tox tox-gh.

Warnings

breaking Drop of Python 3.9 support in v1.6.0. Upgrade to Python >=3.10 to use tox-gh >=1.6.0. ↓

fix Update your CI runners to use Python 3.10 or later.

gotcha tox-gh only works inside GitHub Actions. It will fail or misbehave if run locally or in other CI systems. ↓

fix Provide fallback: use condition like `if: ${{ github.actions }}` or check `GITHUB_ACTIONS` env var in scripts.

deprecated The `tox-gh-action` is deprecated in favor of `tox-gh`. Use the pip-installable plugin approach with a GitHub Actions workflow step. ↓

fix Remove usage of `tox-gh-action` composite action; just `pip install tox tox-gh` and run `tox`.

gotcha If you set `tox_envdir` or customize tox directory, tox-gh may not detect the environment correctly for parallelism or summary. ↓

fix Avoid overriding `tox_envdir` or `work_dir` when using tox-gh.

Quickstart

Minimal GitHub Actions workflow using tox-gh. The plugin is activated automatically; no import or special configuration needed.

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python: ['3.10', '3.11', '3.12']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}
      - name: Install dependencies
        run: pip install tox tox-gh
      - name: Run tox
        run: tox