{"id":17779541,"url":"https://github.com/ymyzk/tox-gh-actions","last_synced_at":"2025-05-14T22:08:35.131Z","repository":{"id":39988420,"uuid":"206941800","full_name":"ymyzk/tox-gh-actions","owner":"ymyzk","description":"Seamless integration of tox into GitHub Actions for tox 3 and 4","archived":false,"fork":false,"pushed_at":"2025-03-03T12:34:02.000Z","size":265,"stargazers_count":253,"open_issues_count":13,"forks_count":26,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-14T04:00:35.862Z","etag":null,"topics":["actions","github-actions","hacktoberfest","python","testing","tox","tox-plugin"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ymyzk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["ymyzk"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2019-09-07T08:53:03.000Z","updated_at":"2025-04-04T09:06:52.000Z","dependencies_parsed_at":"2024-05-12T12:30:15.048Z","dependency_job_id":"e128550e-0d40-4f45-837c-6f17786e7969","html_url":"https://github.com/ymyzk/tox-gh-actions","commit_stats":{"total_commits":200,"total_committers":13,"mean_commits":"15.384615384615385","dds":0.08999999999999997,"last_synced_commit":"21c7bc1c9a1ae77e458a2657a96bde636d7e7190"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ymyzk%2Ftox-gh-actions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ymyzk%2Ftox-gh-actions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ymyzk%2Ftox-gh-actions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ymyzk%2Ftox-gh-actions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ymyzk","download_url":"https://codeload.github.com/ymyzk/tox-gh-actions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254235700,"owners_count":22036964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","github-actions","hacktoberfest","python","testing","tox","tox-plugin"],"created_at":"2024-10-27T01:04:31.104Z","updated_at":"2025-05-14T22:08:30.112Z","avatar_url":"https://github.com/ymyzk.png","language":"Python","funding_links":["https://github.com/sponsors/ymyzk"],"categories":[],"sub_categories":[],"readme":"# tox-gh-actions \u003c!-- omit in toc --\u003e\n\n[![PyPI version](https://badge.fury.io/py/tox-gh-actions.svg)](https://badge.fury.io/py/tox-gh-actions)\n[![PyPI Supported Python Versions](https://img.shields.io/pypi/pyversions/tox-gh-actions.svg)](https://pypi.python.org/pypi/tox-gh-actions/)\n[![GitHub Actions (Tests)](https://github.com/ymyzk/tox-gh-actions/actions/workflows/tests.yml/badge.svg)](https://github.com/ymyzk/tox-gh-actions/actions/workflows/tests.yml)\n[![codecov](https://codecov.io/gh/ymyzk/tox-gh-actions/branch/master/graph/badge.svg?token=7RWjRk2LkX)](https://codecov.io/gh/ymyzk/tox-gh-actions)\n\n**tox-gh-actions** is a tox plugin which helps running tox on GitHub Actions\nwith multiple different Python versions on multiple workers in parallel.\nThis project is inspired by [tox-travis](https://github.com/tox-dev/tox-travis).\n\n- [Features](#features)\n- [Usage](#usage)\n- [Examples](#examples)\n  - [Basic Example](#basic-example)\n    - [tox-gh-actions Configuration](#tox-gh-actions-configuration)\n    - [Workflow Configuration](#workflow-configuration)\n  - [Advanced Examples](#advanced-examples)\n    - [Factor-Conditional Settings: Python Version](#factor-conditional-settings-python-version)\n    - [Factor-Conditional Settings: Environment Variable](#factor-conditional-settings-environment-variable)\n    - [tox requires](#tox-requires)\n  - [Overriding Environments to Run](#overriding-environments-to-run)\n- [Versioning](#versioning)\n- [Versions and Compatibility](#versions-and-compatibility)\n- [Understanding Behavior of tox-gh-actions](#understanding-behavior-of-tox-gh-actions)\n  - [How tox-gh-actions Works](#how-tox-gh-actions-works)\n  - [Logging](#logging)\n\n## Features\nWhen running tox on GitHub Actions, tox-gh-actions\n* detects which environment to run based on configurations and\n* provides utilities such as [grouping log lines](https://github.com/actions/toolkit/blob/main/docs/commands.md#group-and-ungroup-log-lines).\n\n## Usage\n1. Add configurations under `[gh-actions]` section along with tox's configuration.\n   - It will be `pyproject.toml`, `tox.ini`, or `setup.cfg`. See [tox's documentation](https://tox.wiki/en/latest/config.html) for more details.\n\n2. Install `tox-gh-actions` package in the GitHub Actions workflow before running `tox` command.\n\n## Examples\n### Basic Example\nThe following configuration will create 4 jobs when running the workflow on GitHub Actions.\n- On Python 3.7 job, tox runs `py37` environment\n- On Python 3.8 job, tox runs `py38` environment\n- On Python 3.9 job, tox runs `py39` environment\n- On Python 3.10 job, tox runs `py310` and `mypy` environments\n\n#### tox-gh-actions Configuration\nAdd `[gh-actions]` section to the same file as tox's configuration.\n\nIf you're using `tox.ini`:\n```ini\n[tox]\nenvlist = py37, py38, py39, py310, mypy\n\n[gh-actions]\npython =\n    3.7: py37\n    3.8: py38\n    3.9: py39\n    3.10: py310, mypy\n\n[testenv]\n...\n```\n\nIf you're using `setup.cfg`:\n```ini\n[tox:tox]\nenvlist = py37, py38, py39, py310, mypy\n\n[gh-actions]\npython =\n    3.7: py37\n    3.8: py38\n    3.9: py39\n    3.10: py310, mypy\n\n[testenv]\n...\n```\n\nIf you're using `pyproject.toml`:\n```toml\n[tool.tox]\nlegacy_tox_ini = \"\"\"\n[tox]\nenvlist = py37, py38, py39, py310, mypy\n\n[gh-actions]\npython =\n    3.7: py37\n    3.8: py38\n    3.9: py39\n    3.10: py310, mypy\n\n[testenv]\n\"\"\"\n```\n\n#### Workflow Configuration\n`.github/workflows/\u003cworkflow\u003e.yml`:\n```yaml\nname: Python package\n\non:\n  - push\n  - pull_request\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        python-version: ['3.7', '3.8', '3.9', '3.10']\n\n    steps:\n    - uses: actions/checkout@v3\n    - name: Set up Python ${{ matrix.python-version }}\n      uses: actions/setup-python@v4\n      with:\n        python-version: ${{ matrix.python-version }}\n    - name: Install dependencies\n      run: |\n        python -m pip install --upgrade pip\n        python -m pip install tox tox-gh-actions\n    - name: Test with tox\n      run: tox\n```\n\n### Advanced Examples\n#### Factor-Conditional Settings: Python Version\nThe following configuration will create 2 jobs when running the workflow on GitHub Actions.\n- On Python 3.7 job, tox runs `py37-django22` and `py37-django32` environments\n- On Python 3.8 job, tox runs `py38-django32` environment\n\n`tox.ini`:\n```ini\n[tox]\nenvlist = py37-django{22,32}, py38-django32\n\n[gh-actions]\npython =\n    3.7: py37\n    3.8: py38\n\n[testenv]\n...\n```\n\nWhen using pre-release versions of Python, please do not specify `-beta` or `-dev` in `tox.ini`.\n\n`.github/workflows/\u003cworkflow\u003e.yml`:\n```yaml\n...\njobs:\n  build:\n    strategy:\n      matrix:\n        python-version: [3.9, 3.10.0-beta.3]\n...\n```\n\n`tox.ini`:\n```ini\n[tox]\nenvlist = py39, py310\n\n[gh-actions]\npython =\n    3.9: py39\n    3.10: py310\n    # The following won't work\n    # 3.10-beta.3: py310\n    # 3.10-dev: py310\n\n[testenv]\n...\n```\n\nPyPy is also supported in the `python` configuration key.\nSupport of Pyston is experimental and not tested by our CI.\n\n `tox.ini`:\n```ini\n[tox]\nenvlist = py37, py38, pypy3, pyston38\n\n[gh-actions]\npython =\n    3.7: py37\n    3.8: py38, mypy\n    pypy-3.7: pypy3\n    pyston-3.8: pyston38\n\n[testenv]\n...\n\n[testenv:pyston38]\nbasepython = pyston38\n```\n\nYou can also specify without minor versions in the `python` configuration key.\n\n`tox.ini`:\n```ini\n[tox]\nenvlist = py3, pypy3\n\n[gh-actions]\npython =\n    3: py3, mypy\n    pypy-3: pypy3\n\n[testenv]\n...\n```\n\nIf there are multiple matching Python versions in the configuration, only the most precise one is used.\nFor example, if you are running CPython 3.8 and `gh-actions.python` has both `3` and `3.8`,\ntox-gh-actions gets factors only from the key `3.8`.\n\n_Changed in 3.0_: `pypy3` is not supported in the configuration anymore. Please use `pypy-3` instead.\n\n#### Factor-Conditional Settings: Environment Variable\nYou can also use environment variable to decide which environment to run.\nThe following is an example to install different dependency based on platform.\nIt will create 9 jobs when running the workflow on GitHub Actions.\n- On Python 3.8/ubuntu-latest job, tox runs `py38-linux` environment\n- On Python 3.9/ubuntu-latest job, tox runs `py39-linux` environment\n- and so on.\n\n`.github/workflows/\u003cworkflow\u003e.yml`:\n```yaml\nname: Python package\n\non:\n  - push\n  - pull_request\n\njobs:\n  build:\n    runs-on: ${{ matrix.platform }}\n    strategy:\n      matrix:\n        platform: [ubuntu-latest, macos-latest, windows-latest]\n        python-version: ['3.8', '3.9', '3.10']\n\n    steps:\n    - uses: actions/checkout@v3\n    - name: Set up Python ${{ matrix.python-version }}\n      uses: actions/setup-python@v4\n      with:\n        python-version: ${{ matrix.python-version }}\n    - name: Install dependencies\n      run: |\n        python -m pip install --upgrade pip\n        python -m pip install tox tox-gh-actions\n    - name: Test with tox\n      run: tox\n      env:\n        PLATFORM: ${{ matrix.platform }}\n```\n\n`tox.ini`:\n```ini\n[tox]\nenvlist = py{38,39,310}-{linux,macos,windows}\n\n[gh-actions]\npython =\n    3.8: py38\n    3.9: py39\n    3.10: py310\n\n[gh-actions:env]\nPLATFORM =\n    ubuntu-latest: linux\n    macos-latest: macos\n    windows-latest: windows\n\n[testenv]\ndeps =\n  \u003ccommon dependency\u003e\n  linux: \u003cLinux specific deps\u003e\n  macos: \u003cmacOS specific deps\u003e\n  windows: \u003cWindows specific deps\u003e\n...\n```\n\n_Changed in 3.0_: Environment variables should not use lowercase letters.\nBecause of the limitation in tox's configuration loading API,\ntox-gh-actions always convert keys in `[gh-actions:env]` to uppercase.\n\n#### tox requires\nIf your project uses [tox's `requires` configuration](https://tox.wiki/en/latest/config.html#conf-requires),\nyou must add `tox-gh-actions` to the `requires` configuration as well. Otherwise, tox-gh-actions won't be loaded as a tox plugin.\n\n```ini\n[tox]\nrequires =\n  tox-conda\n  tox-gh-actions\n```\n\n### Overriding Environments to Run\n_Changed in 2.0_: When a list of environments to run is specified explicitly via `-e` option or `TOXENV` environment variable ([tox's help](https://tox.wiki/en/latest/cli_interface.html#tox-run--e)),\ntox-gh-actions respects the given environments and simply runs the given environments without enforcing its configuration.\n\nBefore 2.0, tox-gh-actions was always enforcing its configuration even when a list of environments is given explicitly.\n\n## Versioning\nThis project follows [PEP 440](https://www.python.org/dev/peps/pep-0440/) and uses a format of major.minor.patch (X.Y.Z).\nThe major version (X) will be incremented when we make backward incompatible changes to a public API.\nThe public API of this project is the configuration of tox-gh-actions.\nThe major version can be also incremented when we require a new version of tox.\n\nThis project tries not to introduce backward incompatibles changes as much as possible so that users don't need to\nupdate their project's configuration too frequently.\n\ntox-gh-actions 3.x may drop support of unsupported Python 3.y versions in the future without bumping its major version.\n\n## Versions and Compatibility\nWe recommend to use the latest version of tox 4.x and tox-gh-actions 3.x.\nTo use tox-gh-actions with tox 3.x, please install tox-gh-actions 2.x.\nThe following table shows compatibility between tox and tox-gh-actions.\n\n| tox | tox-gh-actions | Supported by tox-gh-actions  | Branch                                                    |\n|-----|----------------|------------------------------|-----------------------------------------------------------|\n| 4.x | 3.x            | Yes (stable)                 | [master](https://github.com/ymyzk/tox-gh-actions)         |\n| 3.x | 2.x            | Only security fixes (stable) | [tox3](https://github.com/ymyzk/tox-gh-actions/tree/tox3) |\n\n## Understanding Behavior of tox-gh-actions\n### How tox-gh-actions Works\nSee [ARCHITECTURE.md](./ARCHITECTURE.md) for more details.\n\n### Logging\ntox-gh-actions writes log messages using the standard `logging` module.\nThis is handy for understanding behavior of tox-gh-actions and for debugging tox-gh-actions.\nTo see the log messages, please run `tox -vv`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fymyzk%2Ftox-gh-actions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fymyzk%2Ftox-gh-actions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fymyzk%2Ftox-gh-actions/lists"}