Tools mentioned in this article
Open the browser-based tool while you read and try the workflow immediately.
The challenge of complexity in GitHub Actions
GitHub Actions is powerful, but workflow YAML tends to balloon as a project grows. Figuring out “which job runs after which” by reading hundreds of lines of code takes far longer than you’d expect.
The GitHub Actions Visualizer turns a pasted workflow YAML into a Mermaid dependency graph instantly. Processing happens entirely in your browser, so sensitive workflow definitions are never sent to a server.

How needs becomes a graph
The visualization is built entirely from each job’s needs field. The dependencies scattered across a YAML file get walked and converted into Mermaid arrows.
jobs:
lint:
runs-on: ubuntu-latest
test:
needs: lint
build:
needs: lint
deploy:
needs: [test, build]
graph TD
lint["lint"]
test["test"]
lint --> test
build["build"]
lint --> build
deploy["deploy"]
test --> deploy
build --> deploy
At a glance, lint is the bottleneck, test and build run in parallel, and deploy is where everything converges — the shape of the pipeline becomes obvious.
needs accepts either a string or an array
GitHub Actions allows needs to be written as a single string for one dependency, or an array for multiple:
needs: lint # a single string is fine
needs: [lint, test] # so is an array
The visualizer handles either form correctly, but knowing this quirk helps when you’re reading someone else’s YAML by hand.
Common pipeline shapes
Once visualized, most workflows turn out to be combinations of a few recurring shapes:
- Fan-out (parallel expansion):
test,lint, andsecurity-scanall running simultaneously afterbuild— the basic pattern for cutting CI time - Fan-in (convergence): multiple jobs completing before converging on
deploy, expressed withneeds: [build, test, lint] - Matrix:
strategy.matrixexpanding one job definition across multiple versions/OSes — a single node in the diagram, but multiple parallel jobs at runtime
Once you see the diagram, a “this should be parallel but got serialized” or “the deploy job’s needs is missing a quality gate” issue tends to jump out — and that’s the starting point for pipeline improvements. For concrete rewrite patterns that speed up CI, see GitHub Actions needs Design Patterns.
A concrete review example
In the configuration below, deploy depends only on test, so it may proceed even if lint fails.
jobs:
lint:
runs-on: ubuntu-latest
test:
runs-on: ubuntu-latest
deploy:
needs: [test]
runs-on: ubuntu-latest
In a diagram, lint appears isolated, which makes it easy to discuss “should the quality check be a deploy prerequisite?” That feeds into design decisions — whether changing deploy’s needs to [lint, test] is enough, or whether to add a build job to share artifacts.
Circular dependencies are caught by GitHub Actions itself
If needs forms a loop (A depends on B, B depends on A), GitHub Actions can’t run the workflow at all and reports an error. Cycles are hard to spot by eye in hundreds of lines of YAML, so visualizing the dependency flow first is the practical shortcut.
Showing runs-on, if and matrix with the details option
Tick “Show details” in the GitHub Actions visualizer and each job’s box gains the information below. Untick it to go back to the old diagram with only job names.
test → test / runs-on: ubuntu-latest / matrix: 6 (+1 include)
deploy → deploy / runs-on: self-hosted, linux / if: github.ref == 'refs/heads/main' / environment: production
call → call / uses: ci.yml@v1
- runs-on: added whether it is a string or an array (
[self-hosted, linux]). - matrix: the number of combinations across the arrays. What
includeadds is written separately as+N include. An expression such as${{ fromJson(…) }}can’t be counted, so it shows(dynamic). - if: added with the
${{ }}removed, and the job’s border becomes dashed, so jobs that don’t always run stand out at a glance. - uses / environment: a job that calls a reusable workflow gets
uses(file name and tag), and one with a deployment target getsenvironment. - Long conditions are cut at 60 characters, and
<>"&become entity references so they can’t break Mermaid’s syntax.
The rich SVG view: read job relationships interactively
Besides the Mermaid graph, the dependencies can be drawn as a custom “rich SVG” (the default view; the Mermaid view and copying the Mermaid code still work as before).
- Stages left to right: one column per
needsdepth, with jobs of the same depth stacked. You can add a frame per stage (headed likeStage 2 · 3) and icons for the job kind (reusable, matrix, deploy) - The longest chain highlighted: the critical path is drawn as a thick orange line, together with the total of its
timeout-minutes(and how many jobs have no timeout) - Matrix jobs as stacked boxes, and dependencies that use
needs.<job>.outputsget an “outputs” label on the line - Click a job box to see its
runs-on, step names andneeds. Hover over it (or focus it with the keyboard) to keep only its upstream and downstream paths - Drag to rearrange: drag a box (or focus it and use the arrow keys) to move it. While you have moved boxes, the stage frames are hidden
- The diagram can be fitted to the width, zoomed, and saved as SVG or PNG
The YAML you enter, the display options and the positions you moved are saved automatically in this browser, so you can pick up where you left off. You can also delete the saved data, or export and import it as JSON. Nothing is sent to a server.
FAQ
How do jobs without needs run?
Jobs with no needs start in parallel when the workflow begins. To control order, specify the dependency explicitly with needs: [job-id]. In a diagram, the boundary between independently running jobs and sequential ones is obvious at a glance.
What happens if dependencies form a cycle?
If needs forms a loop, GitHub Actions cannot run the workflow and reports an error. Cycles are hard to spot in hundreds of lines of YAML, so visualizing it as a DAG (directed acyclic graph) helps.
Is it safe to paste workflow YAML into an external tool?
Workflows may contain secret names and deployment targets. The GitHub Actions Visualizer processes everything in your browser and never sends the YAML to a server, so you can safely diagram such files.
How are matrix builds displayed?
A job expanded via strategy.matrix is defined once, so it appears as a single node in the diagram even though it runs as multiple parallel jobs at execution time. For understanding the needs dependency flow, a single node is enough — you don’t need to see every matrix combination separately.
Summary
- Visualization is just each job’s
needsconverted into Mermaid arrows — the mechanism is simple needsaccepts both string and array notation- Diagramming surfaces “unnecessary serialization,” “unintended parallelism,” and circular dependencies
- For concrete CI-speedup patterns, see the companion needs design-patterns article
When a complex job configuration throws an error, turning it into a diagram first to re-confirm the execution order is usually the fastest way in.
