Actions

Reusable steps and workflows for GitHub Actions, focused on Python packages.

GitHub Actions workflows, actions and documentation are mostly focused on JavaScript/TypeScript as the scripting language for writing reusable CI code. However, Python being equally popular and capable, usage of JS/TS might be bypassed, with some caveats. This repository gathers reusable CI tooling for testing, packaging and distributing Python projects and documentation.

See GitHub Actions and GitHub Reusable Workflows for more background information.

Reusable Actions

• Artifacts:
  pyTooling/upload-artifact: The upload-artifact action will preserve file attributes like permissions.

  pyTooling/download-artifact: The download-artifact action will preserve file attributes like permissions.

Predefined Docker Images

• Documentation:
  MikTeX: A predefined MikTeX image based on Debian Bookworm + Python 3.13 with specific tools for documentation generation using e.g. Sphinx and related extensions.

Reusable Workflows

This repository provides 10+ Reusable Workflows based on the CI pipelines of the repos in this GitHub organisation, EDA², VHDL, and others. By combining them, Python packages can be continuously tested and released along with Sphinx documentation sites, to GitHub Releases, GitHub Pages and PyPI. Optionally, coverage and static type check reports can be gathered and integrated into the online documentation.

As shown in the screenshots above, the expected order is:

• Global:
  Parameters: It generates output parameters with artifact names and job matrices to be used in later running jobs.
  It's a workaround for the limitations to handle global variables in GitHub Actions workflows (see actions/runner#480).

  ExtractConfiguration: extracts configuration values from pyproject.toml and exposes configured paths and filenames as job output parameters.

• Predefined pipelines:
  CompletePipeline: is a predefined pipeline for typical Python projects using all predefined job templates of pyTooling at once: (unit testing, code coverage, static typing, documentation report generation and publishing, packaging, releasing, ...)

• Code testing/analysis:
  ApplicationTesting: like UnitTesting, but running tests using an installed Python package.

  UnitTesting: run unit test with pytest using multiple versions of Python, and optionally upload results as XML reports. Configuration options to pytest should be given via section [tool.pytest.ini_options] in a pyproject.toml file.
  Besides test results, also code coverage data (incl. branch coverage) can be collected using pytest/pytest-cov/coverage.py. Configuration options to coverage.py should be given via section [tool.coverage.*] in a pyproject.toml file.
  While multiple report formats can be created in the job, it's recommended to use PublishTestResults and/or PublishCoverageResults to merge results from matrix runs and then generate final reports as XML, JSON or HTML.
  Finally, reports can be published to GitHub Pages or cloud services like Codecov and Codacy.

  StaticTypeCheck: collect static type check result with mypy, and optionally upload results as an HTML report.

  VerifyDocs: extract code examples from the README and test these code snippets.

• Packaging and releasing:
  Package: generate source and wheel packages, and upload them as an artifact.

  PublishOnPyPI: publish source and wheel packages to PyPI.

  PublishTestResults: publish unit test results through GH action dorny/test-reporter.

  PublishCoverageResults: publish ucode coverage results.

  NightlyRelease: publish GitHub Release.

  Release: publish GitHub Release.

• Documentation:
  SphinxDocumentation: create HTML and LaTeX documentation using Sphinx.

  LaTeXDocumentation: compile LaTeX documentation to a PDF file using MikTeX.

  PublishToGitHubPages: publish HTML documentation to GitHub Pages.

• Cleanup:
  IntermediateCleanUp: delete intermediate artifacts.

  ArtifactCleanUp: delete artifacts.

• ⚠ Deprecated ⚠:
  CoverageCollection: Use UnitTesting, because is can collect code coverage too. This avoids code duplication in job templates.

  BuildTheDocs: Use SphinxDocumentation, LaTeXDocumentation and PublishToGitHubPages. BuildTheDocs isn't maintained anymore.

Example pipeline

ExamplePipeline.yml is an example Workflow which uses all of the Reusable Workflows. Python package/tool developers can copy it into their repos, in order to use al the reusable workflows straightaway. Minimal required modifications are the following:

• Set the name input of job Parameters.
• Specify the commands input of job StaticTypeCheck.

Find further usage cases in the following list of projects:

• edaa-org/pyEDAA.ProjectModel
• edaa-org/pySVModel
• VHDL/pyVHDLModel

Contributors

• Patrick Lehmann
• Unai Martinez-Corral (Maintainer)
• and more...

License

This Python package (source code) licensed under Apache License 2.0. The accompanying documentation is licensed under Creative Commons - Attribution 4.0 (CC-BY 4.0).

---

SPDX-License-Identifier: Apache-2.0