workflows

Reusable workflows

Our main goal is to provide tools for maintainers working on Python 2 projects.

Catalog

Workflows:

• docker-build-push-multi-platform
• pip-compile-upgrade
• pre-commit-autoupdate
• pre-commit
• pylint
• pypi-upload
• tox-docker
• tox-envs
• tox-gh
• tox

.github/workflows/docker-build-push-multi-platform

GitHub action for using a matrix strategy to distribute the build for linux/amd64 and linux/arm64, and publish to a Docker registry of your choice (Docker Hub, ghcr.io or quay.io).

Inputs:

• registry-image (string): Docker image to use as base name for tags.
• metadata-tags (string): List of tags as key-value pair attributes. Optional.
• registry-address (string): Server address of Docker registry. If not set then will default to Docker registry. Optional.
• registry-username (string): Username for authenticating to the Docker registry.
• build-context (string): Build's context is the set of files located in the specified PATH or URL. Optional.
• build-file (string): Path to the Dockerfile. Optional.
• build-provenance (boolean): Generate provenance attestation for the build. Defaults to false. Optional.
• build-cache-key (string): An explicit key for a cache entry. This will be used in conjunction with the platform set in build-platforms, e.g. coatl-linux-amd64. Defaults to coatl. Optional.
• build-digest-key (string): Name of the build digest. This will be used in conjunction with the platform set in build-platforms, e.g. coatl-linux-amd64. Defaults to coatl. Optional.

Secrets:

• registry-password (secret): Password or personal access token for authenticating the Docker registry.

Example:

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/docker-build-push-multi-platform.yml@v4.1.4
    with:
      registry-image: user/app
      metadata-tags: |
        type=semver,pattern={{version}}
        type=semver,pattern={{major}}.{{minor}}
        type=semver,pattern={{major}}
      registry-username: ${{ vars.DOCKERHUB_USERNAME }}
      build-context: "{{defaultContext}}:mysubdir"
      build-provenance: true
      build-cache-key: mykey
      build-digest-key: mydigest
    secrets:
      registry-password: ${{ secrets.DOCKERHUB_TOKEN }}

.github/workflows/pip-compile-upgrade

GitHub action for running pip-compile upgrade on your Python 2 and 3 requirements.

Inputs:

• path (string): A file or location of the requirement file(s).
• python-version (string): Python version to use for installing pip-tools. You may use MAJOR.MINOR or exact version. Defaults to '3.13'. Optional.
• pr-create (string): Whether to create a Pull Request. Options: 'yes', 'no'. Defaults to 'yes'. Optional.
• pr-commit-message (string): Use the given message as the commit message. Defaults to 'chore(requirements): pip-compile upgrade'. Optional.
• pr-auto-merge (string): Automatically merge only after necessary requirements are met. Options: 'yes', 'no'. Defaults to 'yes'. Optional.
• pr-delete-branch (string): Delete the local and remote branch after merge. Options: 'yes', 'no'. Defaults to 'no'. Optional.
• sign-commits (string): Whether to sign Git commits. Options: 'yes', 'no'. Defaults to 'yes'. Optional.

Secrets:

• gh-token (secret): GitHub token. Required when creating PRs, otherwise is optional.
• gpg-sign-passphrase (secret): GPG private key passphrase. Required when signing commits, otherwise is optional.
• gpg-sign-private-key (secret): GPG private key exported as an ASCII armored version. Required when signing commits, otherwise is optional.

Example:

name: pip-compile-upgrade

on:
  schedule:
    - cron: '0 20  * * 1'
  workflow_dispatch:

jobs:
  pip-compile-upgrade:
    uses: coatl-dev/workflows/.github/workflows/pip-compile-upgrade.yml@v4.1.4
    with:
      path: requirements.txt
    secrets:
      gh-token: ${{ secrets.GH_TOKEN }}
      gpg-sign-passphrase: ${{ secrets.GPG_PASSPHRASE }}
      gpg-sign-private-key: ${{ secrets.GPG_PRIVATE_KEY }}

.github/workflows/pre-commit-autoupdate

If you [cannot/do not want to] benefit from pre-commit.ci, use this workflow to install Python and invoke pre-commit autoupdate.

Inputs:

• pr-base-branch (string): The branch into which you want your code merged. Defaults to 'main'. Required when pr-create is set to 'yes', otherwise is optional.
• pr-create (string): Whether to create a Pull Request. Options: 'yes', 'no'. Defaults to 'yes'. Optional.
• pr-auto-merge (string): Automatically merge only after necessary requirements are met. Options: 'yes', 'no'. Defaults to 'yes'. Optional.
• pr-delete-branch (string): Delete the local and remote branch after merge. Options: 'yes', 'no'. Defaults to 'no'. Optional.
• sign-commits (string): Whether to sign Git commits. Options: 'yes', 'no'. Defaults to 'yes'. Optional.
• skip-repos (string): A list of repos to exclude from autoupdate. The repos must be separated by a "pipe" character '|'. Defaults to ''. Optional.

Secrets:

• gh-token (secret): GitHub token. Required when creating PRs, otherwise is optional.
• gpg-sign-passphrase (secret): GPG private key passphrase. Required when signing commits, otherwise is optional.
• gpg-sign-private-key (secret): GPG private key exported as an ASCII armored version. Required when signing commits, otherwise is optional.

Example:

name: pre-commit-autoupdate

on:
  schedule:
    - cron: '0 20 * * 1'
  workflow_dispatch:

jobs:
  pre-commit-autoupdate:
    uses: coatl-dev/workflows/.github/workflows/pre-commit-autoupdate.yml@v4.1.4
    with:
      skip-repos: 'flake8'
    secrets:
      gh-token: ${{ secrets.GH_TOKEN }}
      gpg-sign-passphrase: ${{ secrets.GPG_PASSPHRASE }}
      gpg-sign-private-key: ${{ secrets.GPG_PRIVATE_KEY }}

.github/workflows/pre-commit.yml

If you [cannot/do not want to] benefit from pre-commit.ci, use this workflow to install Python and invoke pre-commit.

Inputs:

• skip-hooks (list[string]): A comma separated list of hook ids which will be disabled. Useful when your pre-commit-config.yaml file contains local hooks. Optional. See: Temporarily disabling hooks.

Example:

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/pre-commit.yml@v4.1.4
    with:
      skip-hooks: 'pylint'

.github/workflows/pylint.yml

This workflow will install Python and invoke pylint to analyze your code.

Example:

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/pylint.yml@v4.1.4

.github/workflows/pypi-upload.yml

This workflow allows you to build and upload your Python distribution packages PyPI (or any other repository) using build and twine.

Note

This workflow uses the coatldev/python Docker image, which has tags for Python 3.13, 3.12 and 2.7.

Inputs:

• python-version (string): The Python version to use for building and publishing the package. You may use MAJOR.MINOR or exact version. Defaults to '3.13'. Optional
• check (boolean): Check metadata with twine before uploading. Defaults to true. Optional.
• url (string): The repository (package index) URL to upload the package to. Defaults to 'https://upload.pypi.org/legacy/'. Optional.
• username (string): The username to authenticate to the repository (package index) as. Defaults to '__token__'. Optional.

Secrets:

• password (secret): The password to authenticate to the repository (package index) with. This can also be a token. Required.

Example:

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/pypi-upload.yml@v4.1.4
    with:
      python-version: '3.13'
    secrets:
      password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/tox-docker.yml

This workflow will install the latest version of tox to run all envs found in env_list.

Note

This workflow uses the coatldev/six Docker image, which comes with Python 3.13, 3.12 and 2.7.18.

Example:

[tox]
requires =
    tox>=4.2
    virtualenv<20.22.0

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/tox-docker.yml@v4.1.4

.github/workflows/tox-envs.yml

This workflow will install Python and invoke tox envs based on the list of Python versions.

Inputs:

• python-versions (list[string]): A list of Python versions passed through to actions/setup-python's python-version. Required.

This action sets the proper tox env based on the Python version. For example: '3.10' will run py310, '3.9' will run py39 and so forth.

Recommendations:

When testing end-of-life Python, e.g. 2.7, you need to add the following requires statement to your tox.ini configuration file:

[tox]
requires =
    virtualenv<20.22.0

Example:

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/tox-envs.yml@v4.1.4
    with:
      python-versions: '["3.9", "3.10", "3.11", "3.12", "3.13"]'

.github/workflows/tox-gh.yml

This workflow will install Python and tox-gh and it will run the matching tox environment based on the gh configuration section found in tox.ini.

Inputs:

• python-versions (list[string]): A list of Python versions passed through to actions/setup-python's python-version. Required.

Important

The latest tox-gh release requires python>=3.7.

Example:

tox.ini:

[gh]
python =
    3.9 = py39
    3.10 = py310
    3.11 = py311
    3.12 = py312
    3.13 = py313, install, typecheck

and on your workflow:

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/tox-gh.yml@v4.1.4
    with:
      python-versions: '["3.9", "3.10", "3.11", "3.12", "3.13"]'

.github/workflows/tox.yml

This workflow will install Python and invoke tox to run all envs found in env_list.

Example:

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/tox.yml@v4.1.4