actions-graph

Visualize your GitHub Actions dependency tree — the npm ls that Actions never got.

GitHub Actions provides zero visibility into transitive dependencies. Composite actions can include other actions, which include others, creating invisible dependency chains. actions-graph parses your workflow YAML files, recursively resolves composite action dependencies via the GitHub API, and produces a visual dependency tree with risk assessment.

Installation

pip install actions-graph

Or with uv:

uv tool install actions-graph

Quick Start

# Show dependency tree (auto-discovers .github/workflows/*.yml)
actions-graph tree

# Limit tree depth
actions-graph tree --depth 3

# Export as Mermaid diagram
actions-graph export --format mermaid

# Export as DOT (Graphviz)
actions-graph export --format dot | dot -Tpng -o graph.png

# Export as JSON
actions-graph export --format json

# Compare two workflow files
actions-graph diff workflow-a.yml workflow-b.yml

# Audit with risk assessment
actions-graph audit

Authentication

Set the GITHUB_TOKEN environment variable for API access. Without it, you'll be rate-limited to 60 requests/hour.

export GITHUB_TOKEN=ghp_your_token_here
actions-graph tree

CLI Reference

actions-graph tree [FILES...] [--depth N] [--no-cache]

Display the dependency tree in the terminal using Rich. If no files are given, auto-discovers workflows in .github/workflows/.

• --depth N — Limit display depth
• --no-cache — Disable the local SQLite cache

actions-graph export [FILES...] --format <mermaid|dot|json> [--no-cache]

Export the dependency graph in one of three formats:

• mermaid — Mermaid flowchart for GitHub PR comments
• dot — Graphviz DOT format (pipe to dot for rendering)
• json — JSON adjacency list with full metadata

actions-graph diff FILE_A FILE_B

Compare two workflow files and display added/removed action dependencies. Useful for reviewing PRs.

actions-graph audit [FILES...] [--no-cache]

Display the dependency tree plus a risk summary. Each action is scored based on:

• Mutable tag — uses a tag (e.g., v4) instead of a pinned SHA
• Unverified creator — action owner is not in the known-good list
• High depth — transitive dependency depth exceeds 3

Risk levels: LOW, MEDIUM, HIGH, CRITICAL (based on number of risk factors).

actions-graph --version

Print version and exit.

Caching

API responses are cached in a SQLite database at ~/.cache/actions-graph/cache.db with a 24-hour TTL. Use --no-cache to bypass.

How It Works

1. Parse — Reads workflow YAML and extracts uses: references
2. Resolve — Fetches action.yml from GitHub API for each action; if composite, recursively resolves child actions
3. Graph — Builds a NetworkX directed graph of all dependencies
4. Assess — Scores each node for risk factors
5. Render — Outputs as Rich tree, Mermaid, DOT, or JSON

Development

git clone https://github.com/your-org/actions-graph
cd actions-graph
uv sync
uv run pytest
uv run ruff check .

Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Ensure uv run pytest and uv run ruff check . pass
5. Submit a pull request

License

MIT — see LICENSE for details.