Pipeline Graph

The jobs of a workflow and their needs form a graph. The gha domain draws it in a Sphinx documentation, so the domain has to be enabled - see Overview.

The gha:pipeline-graph directive draws the pipeline of a GitHub Actions workflow - its jobs and their needs - from the workflow file itself:

  • a job is a node labelled with its name and the file of the reusable workflow it calls;

  • a job running steps is a grey box with square corners;

  • a job with an if condition is dashed, and in HTML its tooltip is the condition;

  • a job with a strategy.matrix is a cluster of its instances, labelled with the matrix’ dimensions; an instance calling a reusable workflow is drawn as the job calling it. A dynamic matrix - its combinations known at run time only - is one node with a double border;

  • a reusable workflow of another repository is a white leaf naming that repository and ref;

  • a reusable workflow of the documented repository is expanded into a cluster of its jobs, as many levels deep as :depth: says - the one an instance of a matrix calls as well;

  • the needs are the edges, without those a longer path implies.

The workflow is read with pyTooling.GitHub.WorkflowFile, converted into a pyTooling.CI model and its Graph (Building a Pipeline), and drawn by sphinx.ext.graphviz. Every workflow file drawn becomes a dependency of the page.

.. gha:pipeline-graph:: Workflows/Pipeline.yml
   :depth: 1
   :caption: The pipeline of Pipeline.yml.

This is how the example renders, drawn from Workflows/Pipeline.yml and Workflows/Test.yml:

Pipeline of Pipeline.yml

The pipeline of Pipeline.yml.

.. gha:pipeline-graph:: <path of a workflow file>

Draws the workflow the argument names, relative to the document.

:depth: <levels>

Levels of reusable workflows of the documented repository to expand into clusters. Default: 0.

:direction: LR | TB

Whether the pipeline flows from left to right or from top to bottom. Default: LR.

:reduce: yes | no

Whether an edge a longer path implies is dropped. Default: yes.

Whether a job links to the page documenting its reusable workflow, in HTML. Default: yes.

:caption: <text>

A caption under the graph.

:name: <label>

A label to reference the graph by.

:align: left | center | right

The graph’s horizontal alignment.

:alt: <text>

The graph’s alternative text. Default: Pipeline of <file name>.

The Documented Repository

A reusable workflow is called by a reference like pyTooling/Actions/.github/workflows/Package.yml@r8. conf.py says which repository the documentation describes, where its workflow files are, and at which ref:

# doc/conf.py
gha_repository =         "pyTooling/Actions"
gha_workflow_directory = "../.github/workflows"
gha_ref =                "r8"

The graph reads the configuration values of the domain (Configuration), and its workflow files through the domain, which reads every file once per build:

  • The reusable workflows of gha_repository are expanded and linked, whatever the ref they are called at. Without it, only local references like ./.github/workflows/Test.yml are.

  • Without gha_workflow_directory, they are read from the directory of the drawn workflow file.

  • A job calling a reusable workflow of the documented repository at another ref than gha_ref is a warning of type gha.ref. Without it, refs aren’t checked.

A job links to the page the gha domain documents its reusable workflow on. Without such a page, and in a format other than HTML, the job has no link.