---

The pyTooling.GitHub Documentation

pyTooling.GitHub works with GitHub Actions pipelines: it reads workflow and action files into a data model, reads the runs of a pipeline from GitHub’s REST API, and converts them into traces - e.g. OpenTelemetry’s OTLP/JSON or a Gantt chart of the jobs and steps. A Sphinx domain gha documents workflows and their inputs, outputs and secrets taken straight from the workflow files.

It builds on pyTooling’s generic CI pipeline model and tracing, and on pyTooling.Sphinx for its documentation extensions.

Attention

The Sphinx domain gha in pyTooling.GitHub.Sphinx requires pyTooling.Sphinx, and thus Python 3.12 or newer, because Sphinx 9.1 requires Python 3.12.

The package is installed from PyPI:

pip install pyTooling.GitHub

Features

Data models

Pipeline runs

→ A GitHub Actions workflow run - pipeline, workflows, matrices, jobs and steps with their times and outcomes - read from the GitHub REST API’s payloads.

Workflow files

→ A workflow file: triggers, inputs, outputs, secrets, permissions and jobs with their dependencies, read with line numbers, and converted into a pipeline graph.

Action files

→ An action’s file: how it runs, and the steps of a composite action with the actions they run in turn.

Sphinx domain gha

The domain needs the extra sphinx, which installs pyTooling.Sphinx:

pip install pyTooling.GitHub[sphinx]

It is enabled in conf.py, and sets up pyTooling.Sphinx itself:

# doc/conf.py
extensions = [
  ...,
  "pyTooling.GitHub.Sphinx",
]

Workflows and their parameters

→ gha:workflow, gha:input, gha:output, gha:secret and gha:autoinputs, taken straight from the workflow file; roles to reference them.

Summaries

→ gha:parameter-table, gha:interface, gha:dependencies and gha:yaml.

Visualization

Pipeline graph

→ gha:pipeline-graph draws the jobs of a workflow and their needs as a Graphviz graph, with the reusable workflows it calls expanded.

Pipeline trace diagram

→ Reads a workflow run through the GitHub REST API into a trace, written as OpenTelemetry’s OTLP/JSON or drawn as a Gantt chart.

Program

Gantt charts need the extra diagram, which installs matplotlib:

pip install pyTooling.GitHub[diagram]

pytooling-github

→ The command pipeline reads a pipeline run into a trace, writes it, and draws it as a Gantt chart.

Consumers

This layer is used by:

• 🚧 pyTooling/Actions - its documentation of the job templates will use the gha domain.

Contributors

• Patrick Lehmann (Maintainer)

• and more…

License

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