gha-graph

See why your GitHub Actions workflow is broken before you push.

GitHub shows your Actions graph after you push. gha-graph shows it locally first — and flags high-confidence workflow footguns like missing needs, dependency cycles, risky pull_request_target checkout, broad token permissions, and oversized matrices.

Quickstart

npx gha-graph --html gha-graph.html
open gha-graph.html

No GitHub token. No hosted service. No tracking. The report is a self-contained HTML/SVG file.

The 10-second win

Broken workflow YAML:

jobs:
  deploy:
    needs: release

But there is no release job. gha-graph shows the broken edge before CI does:

release ──▶ deploy  (missing source)

✖ ERROR unknown-needs
  Job "deploy" needs "release", but no job with that id exists.

What it catches today

• Missing needs dependencies, before GitHub burns a CI run.
• Job dependency cycles.
• pull_request_target workflows that checkout code.
• permissions: write-all at workflow or job scope.
• Pull-request workflows that rely on implicit token permissions.
• Large matrix expansions that can surprise your queue/minutes.
• YAML parse errors with friendly messages.

CLI

gha-graph [path] [options]

path can be a repository root, a .github/workflows directory, or one workflow file.

Options:

--html <file>                 write a self-contained HTML/SVG report
--sarif <file>                write SARIF for GitHub code scanning
--json                        print machine-readable JSON
--explain                     print human-readable explanations and fixes
--mermaid                     print a pasteable Mermaid graph for GitHub Markdown
--no-color                    disable terminal color
--matrix-threshold <number>   warn above this matrix job count (default: 24)
--strict                      exit 1 on warnings as well as errors

HTML report

npx gha-graph . --html gha-graph.html

Human explanation

npx gha-graph . --explain

Mermaid for GitHub Markdown

npx gha-graph . --mermaid > ci-graph.mmd

Paste the output inside a Markdown Mermaid block in an issue, PR, or README.

SARIF for GitHub Code Scanning

npx gha-graph . --sarif gha-graph.sarif

Then upload it in CI with github/codeql-action/upload-sarif.

Use in GitHub Actions

Artifact report on every pull request:

name: gha-graph

on:
  pull_request:

jobs:
  graph:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx gha-graph --html gha-graph.html --sarif gha-graph.sarif
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: gha-graph-report
          path: gha-graph.html
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: gha-graph.sarif

Or use the composite action from this repo:

- uses: feruzkarimovv/[email protected]
  with:
    html: gha-graph.html

Example

npx gha-graph examples/broken-workflow --html gha-graph.html --no-color

Output:

ActionGraph
Scanned 1 workflow(s), 2 job(s). Diagnostics: 2 error, 2 warning, 0 info.

CI with hidden footguns  (.github/workflows/ci.yml)
  on: pull_request_target
  release ──▶ deploy  (missing source)
  • build ×27

Diagnostics
  ! WARNING large-matrix
    Job "build" expands to about 27 matrix jobs.
    Fix: Large matrices can exhaust concurrency or minutes. Consider sharding intentionally or reducing axes.

  ✖ ERROR pull-request-target-checkout
    Job "build" runs on pull_request_target and checks out code.
    Fix: pull_request_target has elevated token context. Never run untrusted PR code without careful pinning and checkout controls.

  ✖ ERROR unknown-needs
    Job "deploy" needs "release", but no job with that id exists.
    Fix: Rename the dependency to one of: build, deploy.

Why not just use the GitHub Actions UI?

GitHub shows a graph after you push. gha-graph gives you the graph and the obvious footguns before the push, locally, in a form you can save, paste into Markdown, upload as SARIF, or attach to a PR.

How it compares

| Tool | What it is great at | Where gha-graph fits | |------|----------------------|-------------------------| | GitHub Actions UI | Official run graph and logs after a workflow runs | Pre-push static topology and warnings | | actionlint | Deep workflow linting | Visual graph + focused explainable footguns; complementary, not a replacement | | act | Local execution of workflows in containers | Static map/report without Docker or cloud parity assumptions | | Bundle/code visualizers | Visualizing application dependencies | gha-graph visualizes CI workflow dependencies |

Philosophy

gha-graph is intentionally conservative. CI diagnostics are only useful if developers trust them, so the first version favors high-confidence checks over pretending to emulate every GitHub Actions expression or runtime detail.

Development

npm install
npm test
npm run typecheck
npm run build
node dist/cli.js examples/broken-workflow --html gha-graph.html --no-color

FAQ

Does it execute my workflow?

No. gha-graph is static. Use act if you need local execution. Use gha-graph when you want an instant map and high-confidence warnings.

Does it need a GitHub token?

No. It reads local workflow files only.

Will it edit my workflow files?

No. It reports issues and suggested fixes. It does not mutate your repository.

Is this a replacement for actionlint?

No. actionlint is excellent. gha-graph is the visual, reportable layer: topology, obvious footguns, Mermaid, SARIF, and a self-contained HTML/SVG artifact.

What is the exit code behavior?

• 0: no errors found.
• 1: errors found, or warnings found with --strict.
• 2: no workflow files found or CLI/runtime error.

Roadmap

• Reusable workflow (workflow_call) relationship graph.
• Optional actionlint integration when available.
• Matrix expansion visualization.
• PR comment/report mode for teams that want gha-graph in CI.

License

MIT