| Name | tox-gh JSON |
| Version |
1.5.0
JSON |
| download |
| home_page | None |
| Summary | Seamless integration of tox into GitHub Actions. |
| upload_time | 2025-01-16 00:46:12 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| 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.9",
"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/4e/0e/6facd007d6f2d0358c133ab3fdcd49a6692470c345f94c482206e0efbdbd/tox_gh-1.5.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.5.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": "",
"digests": {
"blake2b_256": "1362db91eff00205846878e0184d4ba5b24e35cf5540e16b77ea8e5644206dff",
"md5": "d9a79de063f2cdb36715106f88c85507",
"sha256": "fd7e8c826f4576a02af4737fd4b738817660b63898c161d6ee8f658c885f7fa1"
},
"downloads": -1,
"filename": "tox_gh-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d9a79de063f2cdb36715106f88c85507",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 6844,
"upload_time": "2025-01-16T00:46:09",
"upload_time_iso_8601": "2025-01-16T00:46:09.499883Z",
"url": "https://files.pythonhosted.org/packages/13/62/db91eff00205846878e0184d4ba5b24e35cf5540e16b77ea8e5644206dff/tox_gh-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4e0e6facd007d6f2d0358c133ab3fdcd49a6692470c345f94c482206e0efbdbd",
"md5": "ad217d787edc7a09b10d7ac5c70410cd",
"sha256": "bd4c56d1ebcde4ca2450fed347610a739614a7225945bdc89a67c8395eac9d63"
},
"downloads": -1,
"filename": "tox_gh-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "ad217d787edc7a09b10d7ac5c70410cd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 7741,
"upload_time": "2025-01-16T00:46:12",
"upload_time_iso_8601": "2025-01-16T00:46:12.095662Z",
"url": "https://files.pythonhosted.org/packages/4e/0e/6facd007d6f2d0358c133ab3fdcd49a6692470c345f94c482206e0efbdbd/tox_gh-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-16 00:46:12",
"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"
}
