Skip to main content

Seamless integration of tox into GitHub Actions.

Project description

tox-gh

PyPI version PyPI Supported Python Versions check Downloads

tox-gh is a tox plugin, which helps run tox on GitHub Actions with multiple different Python versions on multiple workers in parallel.

Features

When running tox on GitHub Actions, tox-gh:

  • detects, which environment to run based on configurations (or bypass detection and set it explicitly via the TOX_GH_MAJOR_MINOR environment variable),
  • provides utilities such as grouping log lines.

Usage

  1. Add configurations under [gh] section along with your tox configuration.
  2. Install tox-gh package in the GitHub Actions workflow before running tox command.

Examples

Basic Example

Add [gh] section to the same file as tox configuration.

If you're using tox.ini:

[gh]
python =
    3.13 = 3.13, type, dev, pkg_meta
    3.12 = 3.12
    3.11 = 3.11

For tox.toml:

[gh.python]
"3.13" = ["3.13", "type", "pkg_meta"]
"3.12" = ["3.12"]
"3.11" = ["3.11"]

For pyproject.toml:

[tool.tox.gh.python]
"3.13" = ["3.13", "type", "pkg_meta"]
"3.12" = ["3.12"]
"3.11" = ["3.11"]

This will run a different set of tox environments on different python versions set up via GitHub setup-python action:

  • on Python 3.13 job, tox runs 3.13, type and pkg_meta environment,
  • on Python 3.12 job, tox runs 3.12 environment,
  • on Python 3.11 job, tox runs 3.11 environment.

Workflow Configuration

A bare-bones example would be .github/workflows/check.yaml:

jobs:
  test:
    name: test with ${{ matrix.env }} on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        env:
          - "3.13"
          - "3.12"
        os:
          - ubuntu-latest
          - macos-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@v3
      - name: Install tox
        run: uv tool install --python-preference only-managed --python 3.13 tox --with tox-uv --with tox-gh
      - name: Install Python
        if: matrix.env != '3.13'
        run: uv python install --python-preference only-managed ${{ matrix.env }}
      - name: Setup test suite
        run: tox run -vv --notest --skip-missing-interpreters false
        env:
          TOX_GH_MAJOR_MINOR: ${{ matrix.env }}
      - name: Run test suite
        run: tox run --skip-pkg-install
        env:
          TOX_GH_MAJOR_MINOR: ${{ matrix.env }}

A more exhaustive example would be .github/workflows/check.yaml:

name: check
on:
  workflow_dispatch:
  push:
    branches: ["main"]
    tags-ignore: ["**"]
  pull_request:
  schedule:
    - cron: "0 8 * * *"

concurrency:
  group: check-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    name: test with ${{ matrix.env }} on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        env:
          - "3.13"
          - "3.12"
          - "3.11"
        os:
          - ubuntu-latest
          - macos-latest
          - windows-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
          cache-dependency-glob: "pyproject.toml"
          github-token: ${{ secrets.GITHUB_TOKEN }}
      - name: Add .local/bin to Windows PATH
        if: runner.os == 'Windows'
        shell: bash
        run: echo "$USERPROFILE/.local/bin" >> $GITHUB_PATH
      - name: Install tox
        run: uv tool install --python-preference only-managed --python 3.13 tox --with tox-uv --with tox-gh
      - name: Install Python
        if: matrix.env != '3.13'
        run: uv python install --python-preference only-managed ${{ matrix.env }}
      - name: Setup test suite
        run: tox run -vv --notest --skip-missing-interpreters false
        env:
          TOX_GH_MAJOR_MINOR: ${{ matrix.env }}
      - name: Run test suite
        run: tox run --skip-pkg-install
        env:
          TOX_GH_MAJOR_MINOR: ${{ matrix.env }}

FAQ

  • When a list of environments to run is specified explicitly via -e option or TOXENV environment variable tox-gh respects the given environments and simply runs the given environments without enforcing its configuration.
  • The plugin only activates if the environment variable GITHUB_ACTIONS is true.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tox_gh-1.5.0.tar.gz (7.7 kB view details)

Uploaded Source

Built Distribution

tox_gh-1.5.0-py3-none-any.whl (6.8 kB view details)

Uploaded Python 3

File details

Details for the file tox_gh-1.5.0.tar.gz.

File metadata

  • Download URL: tox_gh-1.5.0.tar.gz
  • Upload date:
  • Size: 7.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.0.1 CPython/3.12.8

File hashes

Hashes for tox_gh-1.5.0.tar.gz
Algorithm Hash digest
SHA256 bd4c56d1ebcde4ca2450fed347610a739614a7225945bdc89a67c8395eac9d63
MD5 ad217d787edc7a09b10d7ac5c70410cd
BLAKE2b-256 4e0e6facd007d6f2d0358c133ab3fdcd49a6692470c345f94c482206e0efbdbd

See more details on using hashes here.

Provenance

The following attestation bundles were made for tox_gh-1.5.0.tar.gz:

Publisher: release.yaml on tox-dev/tox-gh

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tox_gh-1.5.0-py3-none-any.whl.

File metadata

  • Download URL: tox_gh-1.5.0-py3-none-any.whl
  • Upload date:
  • Size: 6.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.0.1 CPython/3.12.8

File hashes

Hashes for tox_gh-1.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 fd7e8c826f4576a02af4737fd4b738817660b63898c161d6ee8f658c885f7fa1
MD5 d9a79de063f2cdb36715106f88c85507
BLAKE2b-256 1362db91eff00205846878e0184d4ba5b24e35cf5540e16b77ea8e5644206dff

See more details on using hashes here.

Provenance

The following attestation bundles were made for tox_gh-1.5.0-py3-none-any.whl:

Publisher: release.yaml on tox-dev/tox-gh

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page