workflows

Reusable workflows

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

Catalog

Workflows:

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

.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/[email protected]
    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/docker-build-push-multi-registry

GitHub action for using a matrix strategy to distribute the build for linux/amd64 and linux/arm64, and publish to Docker Hub and quay.io.

Inputs:

• dockerhub-repo (string): Docker Hub repository to push the image to.
• dockerhub-username (string): Username for authenticating to Docker Hub.
• quay-repo (string): Quay repository to push the image to.
• quay-username (string): Username for authenticating to Quay.
• 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-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.
• metadata-tags (string): List of tags as key-value pair attributes. Optional.

Secrets:

• dockerhub-password (secret): Password or personal access token for authenticating against Docker Hub.
• quay-password (secret): Password or personal access token for authenticating against Quay.

Example:

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/[email protected]
    with:
      dockerhub-repo: user/app
      dockerhub-username: ${{ vars.DOCKERHUB_USERNAME }}
      quay-repo: quay.io/user/app
      quay-username: ${{ vars.QUAY_USERNAME }}
      build-context: "{{defaultContext}}:mysubdir"
      build-cache-key: mykey
      build-digest-key: mydigest
      metadata-tags: |
        type=semver,pattern={{version}}
        type=semver,pattern={{major}}.{{minor}}
        type=semver,pattern={{major}}
    secrets:
      dockerhub-password: ${{ secrets.DOCKERHUB_TOKEN }}
      quay-password: ${{ secrets.QUAY_ROBOT_TOKEN }}

.github/workflows/pip-compile-upgrade

GitHub action for running pip-compile upgrade on your Python 2.7 requirements.

Inputs:

• path (string): The location of the requirement file(s).
• extra-args (string): Extra arguments to pass to pip-compile. Optional. Defaults to ''.
• 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.
• working-directory (string): The directory to run the workflow in. Optional. Defaults to github.workspace.

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/[email protected]
    with:
      path: requirements.txt
    secrets:
      gh-token: ${{ secrets.PERSONAL_ACCESS_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/[email protected]
    with:
      skip-repos: 'flake8'
    secrets:
      gh-token: ${{ secrets.PERSONAL_ACCESS_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/[email protected]
    with:
      skip-hooks: 'pylint'

.github/workflows/pylint.yml

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

Inputs:

• path (string): This can be a module, package, directory or a file. Optional.
• extra-args (string): Extra arguments to pass to pylint. Optional. Defaults to ''.
• working-directory (string): The directory to run the workflow in. Optional. Defaults to github.workspace.

Example:

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/[email protected]
    with:
      path: src

.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 ghcr.io/coatl-dev/python-tools Docker image, which has tags for Python 2.7 and 3.12. E.g., ghcr.io/coatl-dev/python-tools:2.7-build.

Inputs:

• python-version (string): The Python version to use for building and publishing the package. Options: '2.7' or '3.12'. Defaults to '2.7'. 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.
• working-directory (string): The directory to run the workflow in. Optional. Defaults to github.workspace.

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/[email protected]
    with:
      python-version: '3.12'
    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.12, 2.7.18 and uv.

Inputs:

• extra-args (string): Extra arguments to pass to tox. Optional. Defaults to ''.
• working-directory (string): The directory to run the workflow in. Optional. Defaults to github.workspace.
• uv-python (string): The Python version to use with uv. Optional. Defaults to '3.14'.

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 =
    tox>=4.2
    virtualenv<20.22.0

Example:

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

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/[email protected]

.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.
• working-directory (string): The directory to run the workflow in. Optional. Defaults to github.workspace.

Important

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

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/[email protected]
    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.

Inputs:

• python-versions (list[string]): Version range or exact version of Python to use, using SemVer's version range syntax. Required.
• extra-args (string): Extra arguments to pass to tox. Optional. Defaults to ''.
• working-directory (string): The directory to run the workflow in. Optional. Defaults to github.workspace.

Note

For more ways to use the python-versions input, please refer to "Using the python-version input" for actions/setup-python.

Example:

jobs:
  main:
    uses: coatl-dev/workflows/.github/workflows/[email protected]
    with:
      python-versions: |
        3.9
        3.10
        3.11
        3.12

.github/workflows/uv-pip-compile-upgrade

GitHub action for running uv pip compile --upgrade on your Python requirements.

Inputs:

• path (string): The location of the requirement file(s).
• python-version (string): The version of Python to set UV_PYTHON to. You may use MAJOR.MINOR or exact version. Options: '3.8' to '3.14'. 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.
• working-directory (string): The directory to run the workflow in. Optional. Defaults to github.workspace.

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: uv-pip-compile-upgrade

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

jobs:
  pip-compile-upgrade:
    uses: coatl-dev/workflows/.github/workflows/[email protected]
    with:
      path: requirements.txt
    secrets:
      gh-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
      gpg-sign-passphrase: ${{ secrets.GPG_PASSPHRASE }}
      gpg-sign-private-key: ${{ secrets.GPG_PRIVATE_KEY }}