tox-gh-actions

A tox plugin that enables seamless integration between tox testing environments and GitHub Actions workflows. The plugin automatically detects which tox environments to run based on the Python version and other factors configured in GitHub Actions matrix strategies, eliminating the need for manual environment selection and enabling efficient parallel testing across multiple Python versions and platforms.

Package Information

• Package Name: tox-gh-actions
• Package Type: pypi
• Language: Python
• Installation: pip install tox-gh-actions

Core Imports

The plugin operates automatically when installed. The only direct import typically needed is for version information:

from tox_gh_actions import __version__

Basic Usage

The plugin operates automatically once installed - no direct Python API calls are needed. Configuration is done through tox configuration files.

Basic Configuration

Add a [gh-actions] section to your tox.ini, setup.cfg, or pyproject.toml:

[tox]
envlist = py37, py38, py39, py310, py311, mypy

[gh-actions]
python =
    3.7: py37
    3.8: py38
    3.9: py39
    3.10: py310
    3.11: py311, mypy

[testenv]
# Your test configuration

GitHub Actions Workflow

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
    
    steps:
    - uses: actions/checkout@v3
    - 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

Architecture

The plugin integrates with tox's plugin system through three main hooks:

• Environment Selection: Analyzes GitHub Actions environment and Python version to determine which tox environments to run
• Log Grouping: Provides GitHub Actions log grouping for better CI output readability
• Configuration Processing: Parses [gh-actions] and [gh-actions:env] sections from tox configuration files

The plugin operates transparently - it detects the GitHub Actions environment, reads the configuration, and automatically overrides tox's envlist to run only the environments appropriate for the current Python version and environment variables.

Capabilities

Package Version

Access to package version information.

__version__: str

Python Version Configuration

Maps Python versions to tox environments in the [gh-actions] section. This is the primary way users configure the plugin.

[gh-actions]
python =
    3.7: py37
    3.8: py38, flake8
    3.9: py39
    3.10: py310, mypy
    3.11: py311
    pypy-3.7: pypy3
    pyston-3.8: pyston38

Supported version formats:

• 3.8: Specific major.minor version
• 3: Major version only
• pypy-3.7: PyPy with specific version
• pyston-3.8: Pyston with specific version

Version matching rules:

• Plugin uses the most specific matching version
• If both 3 and 3.8 are configured, 3.8 takes precedence for Python 3.8
• Plugin checks versions in order of specificity: 3.8 before 3

Environment Variable Configuration

Maps environment variable values to tox factors in the [gh-actions:env] section.

[gh-actions:env]
PLATFORM =
    ubuntu-latest: linux
    macos-latest: macos  
    windows-latest: windows
DATABASE =
    postgresql: pg
    mysql: mysql

Environment variable rules:

• Variable names are automatically converted to uppercase
• Values map to tox environment factors
• Multiple environment variables can be specified
• Factors from different variables are combined with factors from Python version

Plugin Behavior

The plugin automatically handles various scenarios:

Environment Detection:

• Only activates when GITHUB_ACTIONS=true environment variable is present
• Falls back gracefully when not running on GitHub Actions
• Logs warnings when not in GitHub Actions environment

Configuration Handling:

• Respects explicit environment specification via -e option or TOXENV variable
• Uses original envlist when no [gh-actions] configuration is present
• Handles missing or invalid configuration gracefully

Log Management:

• Automatically enables GitHub Actions log grouping for better CI output
• Disables log grouping when parallel execution is used to prevent mixed output

Common Usage Patterns:

# Plugin automatically selects environments based on Python version
tox

# Plugin respects explicit environment selection
tox -e py38,py39

# Plugin respects TOXENV environment variable  
TOXENV=py310,mypy tox

Integration Patterns

Multi-Platform Testing

[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

Complex Factor Combinations

[tox]
envlist = py{38,39}-django{22,32,40}-{sqlite,postgres}

[gh-actions]
python =
    3.8: py38
    3.9: py39

[gh-actions:env]
DATABASE =
    sqlite: sqlite
    postgres: postgres
DJANGO_VERSION =
    2.2: django22
    3.2: django32  
    4.0: django40

Integration with tox requires

[tox]
requires =
    tox-conda
    tox-gh-actions
envlist = py38, py39, py310