Skip to content

SPEC.md

Latest commit

 

History

History
110 lines (74 loc) · 3.26 KB

SPEC.md

File metadata and controls

110 lines (74 loc) · 3.26 KB

actions-graph — Project Specification

24. actions-graph

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

Language Python 3.10+

Distribution PyPI (pip install actions-graph) + GitHub Action

Build Time 5--7 days

License MIT

Category CI-CD / Visualization / Language-Agnostic

Problem

GitHub Actions provides zero visibility into transitive dependencies. Composite actions can include other actions, which include others, creating invisible dependency chains. Unlike npm (npm ls), pip (pipdeptree), or cargo (cargo tree), there's no way to see what you're actually running. A single compromised transitive action can affect thousands of repos.

Solution

A CLI tool that parses workflow YAML files, recursively resolves composite action dependencies via the GitHub API, and produces a visual dependency tree. Highlights security risks: mutable tags, unverified creators, known vulnerabilities, and unused actions.

Core Features

  • Recursive resolution: Follows composite action references recursively to build the full transitive dependency tree.

  • Tree visualization: Renders a terminal dependency tree (like npm ls), with color-coded risk indicators.

  • Graph export: Exports to Mermaid, DOT (Graphviz), and JSON formats for further analysis or documentation.

  • Risk highlighting: Marks each node with risk level based on: mutable tag, unverified creator, known vulnerability, or high depth.

  • Diff mode: Compare two workflow files and show added/removed dependencies. Useful for PR reviews.

  • Caching: Caches resolved action metadata locally to minimize API calls across repeated runs.

Technical Architecture

Python CLI. Parses workflow YAML with PyYAML, extracts uses: references, and recursively fetches action.yml from GitHub API for composite actions. Builds an in-memory DAG (directed acyclic graph) with networkx. Tree rendering uses Rich's tree widget. Graph export uses Mermaid string generation and pydot for DOT format. GitHub API responses are cached in a local SQLite database with configurable TTL.

CLI / API Surface

actions-graph tree # show dependency tree

actions-graph tree --depth 3 # limit depth

actions-graph export --format mermaid # Mermaid diagram

actions-graph export --format dot | dot -Tpng -o graph.png

actions-graph diff main..feature-branch # compare workflows

actions-graph audit # tree + risk assessment

Key Dependencies

  • pyyaml

  • httpx

  • networkx

  • rich

  • typer

  • pydot (optional)

Scope Boundaries

In scope: Workflow parsing, recursive composite action resolution, tree/graph visualization, risk highlighting, Mermaid/DOT/JSON export, diff mode.

Out of scope: Reusable workflow resolution (only actions, not called workflows). Self-hosted runner analysis. Action source code scanning.

Success Criteria

  • Correctly resolves transitive dependencies for 10+ popular composite actions

  • Mermaid output renders correctly in GitHub PR comments

  • Finds at least one unexpected transitive dependency in popular workflows