Parameters

The Parameters job template is a workaround for the limitations of GitHub Actions to handle global variables in GitHub Actions workflows (see actions/runner#480.

It generates output parameters with artifact names and a job matrix to be used in later running jobs.

Behavior:

Todo

Parameters:Behavior Needs documentation.

Dependencies:

None

Instantiation

Simple Example

The following instantiation example creates a job Params derived from job template Parameters version r0. It only requires a name parameter to create the artifact names.

name: Pipeline

on:
  push:
  workflow_dispatch:

jobs:
  Params:
    uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
    with:
      name: pyTooling

Complex Example

The following instantiation example creates 3 jobs from the same template, but with differing input parameters. The first job UnitTestingParams might be used to create a job matrix of unit tests. It creates the cross of default systems (Windows, Ubuntu, macOS, MinGW64, UCRT64) and the given list of Python versions including some mypy versions. In addition a list of excludes (marked as deletions) and includes (marked as additions) is handed over resulting in the following combinations:

Version

3.8 🔴

3.9 🟠

3.10 🟡

3.11 🟢

3.12 🟢

3.13.a1 🟣

pypy-3.8 🔴

pypy-3.9 🟠

pypy-3.10 🟡

Windows 🧊

windows:3.8

windows:3.9

windows:3.10

windows:3.11

windows:pypy-3.9

windows:pypy-3.10

Ubuntu 🐧

ubuntu:3.8

ubuntu:3.9

ubuntu:3.10

ubuntu:3.11

ubuntu:3.12

ubuntu:pypy-3.9

ubuntu:pypy-3.10

macOS 🍎

macos:3.8

macos:3.9

macos:3.10

macos:3.11

macos:3.12

macos:pypy-3.9

macos:pypy-3.10

MSYS 🟪

MinGW32 ⬛

MinGW64 🟦

mingw64:3.11

Clang32 🟫

Clang64 🟧

UCRT64 🟨

 
name: Pipeline

on:
  push:
  workflow_dispatch:

jobs:
  UnitTestingParams:
    uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
    with:
      name: pyTooling
      python_version_list: "3.8 3.9 3.10 3.11 pypy-3.9 pypy-3.10"
      include_list: "ubuntu:3.12 macos:3.12"
      exclude_list: "windows:pypy-3.9 windows:pypy-3.10"

  PerformanceTestingParams:
    uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
    with:
      name: pyTooling
      python_version_list: "3.11 3.12"
      system_list: "ubuntu windows macos"

  PlatformTestingParams:
    uses: pyTooling/Actions/.github/workflows/Parameters.yml@dev
    with:
      name: pyTooling
      python_version_list: "3.12"
      system_list: "ubuntu windows macos mingw32 mingw64 clang64 ucrt64"

Parameters

name

Parameter Name

Required

Type

Default

name

yes

string

— — — —

The name of the library or package.

It’s used to create artifact names.

python_version

Parameter Name

Required

Type

Default

python_version

optional

string

3.12

Python version to be used for all jobs requiring a single Python version.

python_version_list

Parameter Name

Required

Type

Default

python_version_list

optional

string

3.8 3.9 3.10 3.11 3.12

Space separated list of CPython versions and/or mypy version to run tests with.

Possible values:

  • 3.7, 3.8, 3.9, 3.10 , 3.11, 3.12, 3.13

  • pypy-3.7, pypy-3.8, pypy-3.9, pypy-3.10

Icon

Version

Maintained until

Comments

⚫

3.7

2023.06.27

outdated

🔴

3.8

2024.10

🟠

3.9

2025.10

🟡

3.10

2026.10

🟢

3.11

2027.10

🟢

3.12

2028.10

latest

🟣

3.13

2029.10

Python 3.13 alpha (or RC) will be used.

⟲⚫

pypy-3.7

????.??

⟲🔴

pypy-3.8

????.??

⟲🟠

pypy-3.9

????.??

⟲🟡

pypy-3.10

????.??

system_list

Parameter Name

Required

Type

Default

system_list

optional

string

ubuntu windows macos mingw64 ucrt64

Space separated list of systems to run tests on.

Possible values:

  • Native systems: ubuntu, windows, macos

  • MSYS2: msys, mingw32, mingw64, clang32, clang64, ucrt64

Icon

System

Used version

Comments

🧊

Windows

Windows Server 2022 (latest)

🐧

Ubuntu

Ubuntu 22.04 (LTS) (latest)

🍎

macOS

macOS Monterey 12 (latest)

While this marked latest, macOS Ventura 13 is already provided.

🟪

MSYS

⬛

MinGW32

🟦

MinGW64

🟫

Clang32

🟧

Clang64

🟨

UCRT64

Source: Images provided by GitHub

include_list

Parameter Name

Required

Type

Default

include_list

optional

string

""

Space separated list of system:python items to be included into the list of test.

Example:

include_list: "ubuntu:3.11 macos:3.11"

exclude_list

Parameter Name

Required

Type

Default

exclude_list

optional

string

""

Space separated list of system:python items to be excluded from the list of test.

Example:

exclude_list: "windows:pypy-3.8 windows:pypy-3.9"

disable_list

Parameter Name

Required

Type

Default

disable_list

optional

string

""

Space separated list of system:python items to be temporarily disabled from the list of test.

Each disabled item creates a warning in the workflow log:

../_images/GH_Workflow_DisabledJobsWarnings.png

Example:

disable_list: "windows:3.10 windows:3.11"

Secrets

This job template needs no secrets.

Results

python_version

A single string parameter representing the default Python version that should be used across multiple jobs in the same pipeline.

Such a parameter is needed as a workaround, because GitHub Actions doesn’t support proper handling of global pipeline variables. Thus, this job is used to compute an output parameter that can be reused in other jobs.

Usage Example:

jobs:
  Params:
    uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
    with:
      name: pyTooling

  CodeCoverage:
    uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r0
    needs:
      - Params
    with:
      python_version: ${{ needs.Params.outputs.python_version }}

python_jobs

A list of dictionaries containing a job description.

A job description contains the following key-value pairs:

  • sysicon - icon to display

  • system - name of the system

  • runs-on - virtual machine image and base operating system

  • runtime - name of the runtime environment if not running natively on the VM image

  • shell - name of the shell

  • pyicon - icon for CPython or pypy

  • python - Python version

  • envname - full name of the selected environment

Usage Example:

jobs:
  Params:
    uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
    with:
      name: pyTooling

  UnitTesting:
    uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@dev
    needs:
      - Params
    with:
      jobs: ${{ needs.Params.outputs.python_jobs }}

This list can be unpacked with fromJson(...) in a job strategy:matrix:include:

UnitTesting:
  name: ${{ matrix.sysicon }} ${{ matrix.pyicon }} Unit Tests using Python ${{ matrix.python }}
  runs-on: ${{ matrix.runs-on }}

  strategy:
    matrix:
      include: ${{ fromJson(inputs.jobs) }}

  defaults:
    run:
      shell: ${{ matrix.shell }}

  steps:
    - name: 🐍 Setup Python ${{ matrix.python }}
      if: matrix.system != 'msys2'
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python }}

artifact_names

A dictionary of artifact names sharing a common prefix.

The supported artifacts are:

  • unittesting_xml - UnitTesting XML summary report

  • unittesting_html - UnitTesting HTML summary report

  • codecoverage_sqlite - Code Coverage internal database (SQLite)

  • codecoverage_json - Code Coverage JSON report

  • codecoverage_xml - Code Coverage XML report

  • codecoverage_html - Code Coverage HTML report

  • statictyping_html - Static Type Checking HTML report

  • package_all - Packaged Python project (multiple formats)

  • documentation_pdf - Documentation in PDF format

  • documentation_html - Documentation in HTML format

Usage Example:

jobs:
  Params:
    uses: pyTooling/Actions/.github/workflows/Parameters.yml@r0
    with:
      name: pyTooling

  Coverage:
    uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@dev
    needs:
      - Params
    with:
      artifact: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }}

Params

Attention

Params is deprecated.

  • params['unittesting'] → artifact_names['unittesting_xml']

  • params['coverage'] → artifact_names['codecoverage_xml']

  • params['typing'] → artifact_names['statictyping_html']

  • params['package'] → artifact_names['package_all']

  • params['doc'] → artifact_names['documentation_html']