Competing Solutions

Each feature group has competitors solving a part of its task; none of them reads workflow files, action files and pipeline runs into one model, which a Sphinx domain and the visualizations build on.

Outside Python, zizmor has typed models of workflows, actions and Dependabot files - the Rust crate github-actions-models - and checks a workflow for security problems, as a template injection or an unpinned action. actionlint, written in Go, checks a file’s syntax and expressions, the needs of its jobs and the inputs of the reusable workflows it calls. Both are installed from PyPI as command line tools, so a Python program gets their findings, not a model.

A pipeline run becomes a trace by the GitHub receiver of the OpenTelemetry Collector - fed by GitHub’s webhooks, it traces runs as they happen - or by the GitHub Action otel-export-trace-action, which exports a finished run to an OTLP endpoint.

Workflow and Action Files

No package on PyPI reads a workflow file or an action file into a Python object model. The packages below check a workflow file, or write one.

JSON Schema

Source: the schemas of SchemaStore, checked by check-jsonschema, compared to Workflow File.

Disadvantages

  • A file is validated against the schema. A program reading it gets nested dictionaries and lists.

  • Classes generated from the schema - e.g. by datamodel-code-generator - are typed, but know neither the line of an element nor its parent, and don’t check the needs of a job.

Advantages

  • The schema is used by editors too, so a file is checked the same way while it is written.

Workflow Generators

Source: github-actions-cdk, pygha, compared to Workflow File.

Disadvantages

  • They write a workflow file from Python code, but don’t read one.

Pipeline Runs

The packages below are clients of the whole GitHub REST API, including the endpoints of workflow runs and jobs Pipeline Run reads. What they return has the shape of the REST API’s payloads.

PyGithub

Source: PyGithub, on PyPI as PyGithub, compared to Pipeline Run and Pipeline Trace Diagram.

Disadvantages

  • Five dependencies: pynacl, requests, pyjwt, typing-extensions and urllib3.

  • WorkflowRun.jobs() returns a flat list of WorkflowJob objects. The called workflows and matrices a job belongs to are only part of its name - Caller / Build (ubuntu, 3.14) -, and a run is not converted into a trace.

Advantages

  • The whole REST API, including writes like re-running a job, and the authentication of a GitHub App.

githubkit

Source: githubkit, on PyPI as githubkit, compared to Pipeline Run.

Disadvantages

  • Five dependencies: anyio, httpx, hishel, typing-extensions and pydantic, and the generated models in githubkit-schemas.

  • Its models are generated from GitHub’s description of the REST API, so they type the payloads, but form no tree.

Advantages

  • Synchronous and asynchronous requests, and typed models of every payload.

ghapi

Source: ghapi, on PyPI as ghapi, compared to Pipeline Run.

Disadvantages

  • A thin client: an answer is the payload, as a dictionary with attribute access.

Advantages

  • Every endpoint of the REST API, generated from its description.

Workflow Documentation

sphinx-gha

Source: sphinx-gha, on PyPI as sphinx-gha, compared to the gha domain.

Disadvantages

  • It registers its Sphinx domain under the same name, gha, so the two extensions can’t be enabled in one project.

  • What an action’s file can’t say - an example, an environment variable - is written into the YAML file, as keys prefixed with x-.

  • Its documentation names neither a graph of the jobs nor summaries of a workflow’s permissions or dependencies.

Advantages

  • It documents actions too - the inputs, outputs and environment variables of an action.yml -, and writes a usage example.

  • It runs on Python 3.10 and Sphinx 7.4 or newer.

github-actions-docs

Source: github-actions-docs, on PyPI as github-actions-docs, compared to the gha domain.

Disadvantages

  • A command line program writing Markdown - a README.md next to an action, and for the reusable workflows below .github/workflows -, not a part of a Sphinx build.

  • It requires ruamel.yaml <= 0.18.0, while this package requires ruamel.yaml ~= 0.19.1.

Advantages

  • The README.md is rendered by GitHub itself, next to the action.