Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
arrow-right-circle

GitHub Action

dynamic-matrix

v2.1.0

dynamic-matrix

arrow-right-circle

dynamic-matrix

Generate Dynamic Job Matrix for Python

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: dynamic-matrix

              
  uses: coactions/dynamic-matrix@v2.1.0
Learn more about this action in coactions/dynamic-matrix

Choose a version

matrix

GitHub Action that returns a dynamic test matrix. Currently it supports projects using:

  • python and tox

Supported optional arguments:

  • min_python - Minimal version of python to be tested against, default is "3.8". The maximum value is currently "3.13"
  • other_names- A list of other tox environments to include in the matrix. We plan to read them from envlist field in tox.ini.
  • platforms - Default to linux only but can be linux, windows, macos or a combination of them (comma separated).
  • linux: matrix expansion strategy for Linux, full or minmax.
  • windows: matrix expansion strategy for Windows, full or minmax.
  • macos: matrix expansion strategy for MacOS, full or minmax.
  • skip_explode: pass 1 if you want to avoid generating implicit pyXY jobs.

Examples

Simple workflow using coactions/dynamic-matrix

# .github/workflows/tox.yml (your workflow file)
---
jobs:
  pre: # <-- this runs before your real matrix job
    name: pre
    runs-on: ubuntu-24.04
    outputs:
      matrix: ${{ steps.generate_matrix.outputs.matrix }}
    steps:
      - name: Determine matrix
        id: generate_matrix
        uses: coactions/dynamic-matrix@v1
        with:
          other_names: |
            lint
            pkg

  build:
    name: ${{ matrix.name }}
    runs-on: ${{ matrix.os || 'ubuntu-24.04' }}
    needs: pre
    strategy: # this the magic part, entire matrix comes from pre job!
      matrix: ${{ fromJson(needs.pre.outputs.matrix) }}

    steps: # common steps used to test with tox
      - uses: actions/checkout@main
        with:
          fetch-depth: 0

      - name: Set up python ${{ matrix.python_version }}
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python_version }}

      - name: Install tox
        run: |
          python -m pip install -U pip
          pip install tox

      - run: tox run -e ${{ matrix.passed_name }}

Q&A

Which projects using tox would benefit from this GitHub Action?

If your tox envlist is simple, like lint,packaging,py{36,37,38,39} you are among the best candidates to make use of it as that is the primary usage case it covers. If you use environments combining multiple factors, you will need to specify them in other_names argument.

Why this action does not just load envlist values?

We plan to add support for this in the future but it might not be as simple as one would assume. For historical reasons envlist do very often already include python versions instead of generic py entry or they are outdated. The repository code is not available at the time this action runs.

Why only Linux testing is enabled by default?

Linux runners are the fastest ones and many Python projects do not need to support platforms like Windows or macOS. That is why the default platform contains only lines. Still, you can enable all of them by specifying platforms: linux,windows,macos in the action arguments.

Why Windows and MacOS matrix expansion strategy is different than Linux one?

The defaults for macOS and Windows are minmax while for Linux is full. This limit resource usage low while still providing a good level of testing. If your pythons are py38,py39,py310,py311 unless you specify windows: full you will see only two Windows based jobs in the generated matrix: py38 and py311.

What is the difference between name and passed_name in generated matrix?

name is aimed to be the job name displayed in GHA, while passed_name is the tox environment name. We did not name it tox_env because we plan to add support for other testing frameworks, which might use different terminology.

Why is other_names a multiline string instead of being comma separated?

We wanted to allow users to chain (group) multiple tox environments in a single command like tox run -e lint,packaging, and this means that we needed to allow users to use commas as part of a valid name, without splitting on it.