This is a composite GitHub Action for running CI tasks through tox.

The action:

1. Sets up Python
2. Installs/updates pip along with tox and any other tox plugins such as tox-docker
3. Caches the tox environment
4. Runs tox with the environments you specify

name: Python CI

"on":
  push:
    tags:
      - "*"
    branches:
      - "main"
  pull_request: {}

jobs:
  tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python:
          - "3.8"
          - "3.9"
          - "3.10"

    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0 # full history for setuptools_scm

      - name: Run tox
        uses: lsst-sqre/run-tox@v1
        with:
          python-version: ${{ matrix.python }}
          tox-envs: "typing,py"

• python-version (string, required) the Python version.
• tox-envs (string, required) the tox environments to run, as a comma-delimited list. Example: typing,py to run a type checking environment and the Python environment.
• tox-package (string, optional) Pip requirement for tox itself (argument to pip install). Default is tox, without any version constraints.
• tox-plugins (string, optional) Pip requirements for any tox plugins (arguments to pip install). Default is an empty string, but can be set to tox-docker to install Docker support, for example.
• tox-requirements (string, optional) Pip requirements file for the tox package and any plugins. If set, tox-package and tox-plugins are ignored, and instead all dependencies in this file are installed. This should include the tox package and any desired plugins. Default is an empty string.
• tox-posargs (string, optional) Command line arguments to pass to the tox command. The positional arguments are made available as the {posargs} substitution to tox environments. Default is an empty string.
• cache-key-prefix (string, optional) Prefix for the tox environment cache key. Set to distinguish from other caches. Default is tox.
• use-cache (boolean, optional) Flag is enable caching of the tox environment. Default is true.
• working-directory (string, optional) Directory to run tox in. Default is the repository root.

No outputs.

tox-docker is a plugin that lets you run Docker containers during your tox environment runs. This is a great way for your tests to use services like Postgres or Redis. To make tox-docker available, specify it in the tox-plugins argument:

name: Python CI

"on":
  push:
    tags:
      - "*"
    branches:
      - "main"
  pull_request: {}

jobs:
  tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python:
          - "3.11"
          - "3.12"

    steps:
      - uses: actions/checkout@v4

      - name: Run tox
        uses: lsst-sqre/run-tox@v1
        with:
          python-version: ${{ matrix.python }}
          tox-envs: "typing,py"
          tox-plugins: "tox-docker"

Alternately, you can specify tox and tox plugin dependencies from a requirements.txt file referenced with tox-requirements. When you use tox-requirements, the tox-package and tox-plugins options are ignored:

name: Python CI

"on":
  push:
    tags:
      - "*"
    branches:
      - "main"
  pull_request: {}

jobs:
  tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python:
          - "3.11"
          - "3.12"

    steps:
      - uses: actions/checkout@v4

      - name: Run tox
        uses: lsst-sqre/run-tox@v1
        with:
          python-version: ${{ matrix.python }}
          tox-requirements: "requirements/tox.txt"

This requirements file may a frozen dependency file, such as that generated by uv pip compile, in order to pin tox and any plugins to a specific tested version.

uv is a fast reimplementation of pip and several related programs. Using it may speed up creation of the tox virtual environments. To do so, add the tox-uv plugin to either tox-plugins or the requirements file referenced by tox-requirements.

This repository provides a composite GitHub Action, a type of action that packages multiple regular actions into a single step. We do this to make the GitHub Actions workflows of all our software projects more consistent and easier to maintain. You can learn more about composite actions in the GitHub documentation.

Create new releases using the GitHub Releases UI and assign a tag with a semantic version, including a v prefix. Choose the semantic version based on compatibility for users of this workflow. If backwards compatibility is broken, bump the major version.

When a release is made, a new major version tag (i.e. v1, v2) is also made or moved using nowactions/update-majorver. We generally expect that most users will track these major version tags.