| Name | tox-gh JSON |
| Version |
1.6.0
JSON |
| download |
| home_page | None |
| Summary | Seamless integration of tox into GitHub Actions. |
| upload_time | 2025-10-09 20:50:38 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
environments
isolated
testing
virtual
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# tox-gh
[](https://badge.fury.io/py/tox-gh)
[](https://pypi.python.org/pypi/tox-gh/)
[](https://github.com/tox-dev/tox-gh/actions/workflows/check.yaml)
[](https://pepy.tech/project/tox-gh)
**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](https://github.com/actions/toolkit/blob/main/docs/commands.md#group-and-ungroup-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`:
```ini
[gh]
python =
3.13 = 3.13, type, dev, pkg_meta
3.12 = 3.12
3.11 = 3.11
```
For `tox.toml`:
```toml
[gh.python]
"3.13" = ["3.13", "type", "pkg_meta"]
"3.12" = ["3.12"]
"3.11" = ["3.11"]
```
For `pyproject.toml`:
```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`:
```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`:
```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`.
Raw data
{
"_id": null,
"home_page": null,
"name": "tox-gh",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Bern\u00e1t G\u00e1bor <gaborjbernat@gmail.com>",
"keywords": "environments, isolated, testing, virtual",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ad/6f/879f6f469a8ca790cc5e6d9915eba7aed835398c406d81cfa5544c7e6262/tox_gh-1.6.0.tar.gz",
"platform": null,
"description": "# tox-gh\n\n[](https://badge.fury.io/py/tox-gh)\n[](https://pypi.python.org/pypi/tox-gh/)\n[](https://github.com/tox-dev/tox-gh/actions/workflows/check.yaml)\n[](https://pepy.tech/project/tox-gh)\n\n**tox-gh** is a tox plugin, which helps run tox on GitHub Actions with multiple different Python versions on multiple\nworkers in parallel.\n\n## Features\n\nWhen running tox on GitHub Actions, tox-gh:\n\n- detects, which environment to run based on configurations (or bypass detection and set it explicitly via the\n `TOX_GH_MAJOR_MINOR` environment variable),\n- provides utilities such as\n [grouping log lines](https://github.com/actions/toolkit/blob/main/docs/commands.md#group-and-ungroup-log-lines).\n\n## Usage\n\n1. Add configurations under `[gh]` section along with your tox configuration.\n2. Install `tox-gh` package in the GitHub Actions workflow before running `tox` command.\n\n## Examples\n\n### Basic Example\n\nAdd `[gh]` section to the same file as tox configuration.\n\nIf you're using `tox.ini`:\n\n```ini\n[gh]\npython =\n 3.13 = 3.13, type, dev, pkg_meta\n 3.12 = 3.12\n 3.11 = 3.11\n```\n\nFor `tox.toml`:\n\n```toml\n[gh.python]\n\"3.13\" = [\"3.13\", \"type\", \"pkg_meta\"]\n\"3.12\" = [\"3.12\"]\n\"3.11\" = [\"3.11\"]\n```\n\nFor `pyproject.toml`:\n\n```toml\n[tool.tox.gh.python]\n\"3.13\" = [\"3.13\", \"type\", \"pkg_meta\"]\n\"3.12\" = [\"3.12\"]\n\"3.11\" = [\"3.11\"]\n```\n\nThis will run a different set of tox environments on different python versions set up via GitHub `setup-python` action:\n\n- on Python 3.13 job, tox runs `3.13`, `type` and `pkg_meta` environment,\n- on Python 3.12 job, tox runs `3.12` environment,\n- on Python 3.11 job, tox runs `3.11` environment.\n\n#### Workflow Configuration\n\nA bare-bones example would be `.github/workflows/check.yaml`:\n\n```yaml\njobs:\n test:\n name: test with ${{ matrix.env }} on ${{ matrix.os }}\n runs-on: ${{ matrix.os }}\n strategy:\n fail-fast: false\n matrix:\n env:\n - \"3.13\"\n - \"3.12\"\n os:\n - ubuntu-latest\n - macos-latest\n steps:\n - uses: actions/checkout@v4\n - name: Install the latest version of uv\n uses: astral-sh/setup-uv@v3\n - name: Install tox\n run: uv tool install --python-preference only-managed --python 3.13 tox --with tox-uv --with tox-gh\n - name: Install Python\n if: matrix.env != '3.13'\n run: uv python install --python-preference only-managed ${{ matrix.env }}\n - name: Setup test suite\n run: tox run -vv --notest --skip-missing-interpreters false\n env:\n TOX_GH_MAJOR_MINOR: ${{ matrix.env }}\n - name: Run test suite\n run: tox run --skip-pkg-install\n env:\n TOX_GH_MAJOR_MINOR: ${{ matrix.env }}\n```\n\nA more exhaustive example would be `.github/workflows/check.yaml`:\n\n```yaml\nname: check\non:\n workflow_dispatch:\n push:\n branches: [\"main\"]\n tags-ignore: [\"**\"]\n pull_request:\n schedule:\n - cron: \"0 8 * * *\"\n\nconcurrency:\n group: check-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n test:\n name: test with ${{ matrix.env }} on ${{ matrix.os }}\n runs-on: ${{ matrix.os }}\n strategy:\n fail-fast: false\n matrix:\n env:\n - \"3.13\"\n - \"3.12\"\n - \"3.11\"\n os:\n - ubuntu-latest\n - macos-latest\n - windows-latest\n steps:\n - uses: actions/checkout@v4\n with:\n fetch-depth: 0\n - name: Install the latest version of uv\n uses: astral-sh/setup-uv@v3\n with:\n enable-cache: true\n cache-dependency-glob: \"pyproject.toml\"\n github-token: ${{ secrets.GITHUB_TOKEN }}\n - name: Add .local/bin to Windows PATH\n if: runner.os == 'Windows'\n shell: bash\n run: echo \"$USERPROFILE/.local/bin\" >> $GITHUB_PATH\n - name: Install tox\n run: uv tool install --python-preference only-managed --python 3.13 tox --with tox-uv --with tox-gh\n - name: Install Python\n if: matrix.env != '3.13'\n run: uv python install --python-preference only-managed ${{ matrix.env }}\n - name: Setup test suite\n run: tox run -vv --notest --skip-missing-interpreters false\n env:\n TOX_GH_MAJOR_MINOR: ${{ matrix.env }}\n - name: Run test suite\n run: tox run --skip-pkg-install\n env:\n TOX_GH_MAJOR_MINOR: ${{ matrix.env }}\n```\n\n## FAQ\n\n- When a list of environments to run is specified explicitly via `-e` option or `TOXENV` environment variable `tox-gh`\n respects the given environments and simply runs the given environments without enforcing its configuration.\n- The plugin only activates if the environment variable `GITHUB_ACTIONS` is `true`.\n",
"bugtrack_url": null,
"license": null,
"summary": "Seamless integration of tox into GitHub Actions.",
"version": "1.6.0",
"project_urls": {
"Documentation": "https://github.com/tox-dev/tox-gh#tox-gh",
"Homepage": "https://github.com/tox-dev/tox-gh",
"Source": "https://github.com/tox-dev/tox-gh",
"Tracker": "https://github.com/tox-dev/tox-gh/issues"
},
"split_keywords": [
"environments",
" isolated",
" testing",
" virtual"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6733fe63750dc4908448acda6fbe8470bbbf3290ab140be57de7ceb2be7afed6",
"md5": "7794c5b18e751c0a02f47d556c3325db",
"sha256": "871a82fb23a6013db51e8f0a95254bf3270973906d582f6216b3c26546f764d2"
},
"downloads": -1,
"filename": "tox_gh-1.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7794c5b18e751c0a02f47d556c3325db",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 6929,
"upload_time": "2025-10-09T20:50:36",
"upload_time_iso_8601": "2025-10-09T20:50:36.089632Z",
"url": "https://files.pythonhosted.org/packages/67/33/fe63750dc4908448acda6fbe8470bbbf3290ab140be57de7ceb2be7afed6/tox_gh-1.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ad6f879f6f469a8ca790cc5e6d9915eba7aed835398c406d81cfa5544c7e6262",
"md5": "fb8f39d0492670b7bc5c4844e15bdd8c",
"sha256": "b575563926604d85c4fba150a7573f33924e3c37f3496a7563f0d9d7a9db7767"
},
"downloads": -1,
"filename": "tox_gh-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "fb8f39d0492670b7bc5c4844e15bdd8c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 7786,
"upload_time": "2025-10-09T20:50:38",
"upload_time_iso_8601": "2025-10-09T20:50:38.408630Z",
"url": "https://files.pythonhosted.org/packages/ad/6f/879f6f469a8ca790cc5e6d9915eba7aed835398c406d81cfa5544c7e6262/tox_gh-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-09 20:50:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tox-dev",
"github_project": "tox-gh#tox-gh",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tox-gh"
}
