pyTooling.GitHub

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 ghactions 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.

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 ghactions

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 - ghactions:workflow, ghactions:input, ghactions:output, ghactions:secret and ghactions:autoinputs, taken straight from the workflow file; roles to reference them.
• Summaries - ghactions:parameter-table, ghactions:interface, ghactions:dependencies and ghactions:yaml.

Visualization

• Pipeline graph - ghactions: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 ghactions 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).

SPDX-License-Identifier: Apache-2.0