GHA Tree Builder#

Map GitHub Actions workflows into a dependency graph that includes trigger nodes, workflow nodes, and job nodes. The output is DOT syntax so you can render with Graphviz or any compatible tool. If you have Graphviz installed and in your PATH, the tool can also render directly to PNG, SVG, WEBP, or other formats.

Example Usage#

❯ uv run "https://tools.karlquinsland.com/tools/python/gha-tree-builder/tool.py"

# If no --workflow-root directory is specified, assume $PWD.
# If no --output, assume $PWD/gha-tree.dot
./tool.py

# Same defaults, but also render a PNG (requires Graphviz in PATH)
./tool.py --render=gha-tree.png

# Render WEBP and skip writing the DOT file
./tool.py --render=gha-tree.webp --no-dot

# Respect explicit CLI options
./tool.py --workflow-root=/mnt/some/example/.github/workflows \
  --output=/mnt/other/location/example.dot

# Allow env-vars to set CLI args as well
GHA_TREE_BUILDER_WORKFLOW_ROOT=/mnt/some/example/.github/workflows \
  ./tool.py --output=/mnt/other/location/example.dot

# Limit parsing to matching workflow files
./tool.py some-prefix*.yaml

# Include or exclude specific workflow files (mutually exclusive)
./tool.py --workflow-root=.github/workflows --include-glob='some-prefix*.yaml'
./tool.py --workflow-root=.github/workflows --exclude-glob='*-legacy.yml'

Example Output#

Using this repo’s current (as of a693950) GHA workflows as an example, this command:

❯ uv run ./content/tools/python/gha-tree-builder/tool.py --render=./content/tools/python/gha-tree-builder/images/example01.png --workflow-root=.github/workflows
# <...>
2026-01-21 17:53:42 [info     ] render_written                 output=content/tools/python/gha-tree-builder/images/example01.png

Produces the following output:

Example GHA Tree