Free GitHub Actions Workflow Visualizer
Paste a workflow file to see which jobs run in parallel, which wait on others, and what triggers the whole run.
What is a GitHub Actions Workflow Visualizer?
A GitHub Actions workflow is a YAML file of jobs, and the needs key decides which jobs wait for others. This visualizer draws a workflow as a diagram, from its triggers through every job, so you can see the order GitHub will run them in.
It reads the on, jobs, needs, runs-on, uses, strategy and if keys as GitHub’s workflow syntax reference defines them. Before drawing, it checks that every needs entry names a real job and that no jobs wait on each other in a loop, the mistakes GitHub reports as an invalid workflow.
Key Features
Parallel and Sequential Jobs at a Glance
Jobs with no needs hang off the trigger and run in parallel, and arrows show which jobs wait. Bottlenecks in a pipeline become obvious.
Broken Needs Caught Before You Push
A needs entry that names a missing job, or jobs that need each other, is reported with the job IDs involved instead of failing on GitHub.
Runners, Matrices and Conditions Shown
Each job shows its runner or runner labels, its matrix dimensions and any if condition. Reusable-workflow calls show the workflow they use.
Every Trigger in One Place
Triggers written as a string, a list or a map, such as push, pull_request and schedule, are collected into the starting node.
Copyable Mermaid Diagram
Switch to Mermaid source to paste the graph into a README or pull request, where GitHub renders it as the same diagram.
Perfect for everyone
- Developers maintaining CI pipelines
- Platform engineers reviewing workflow changes
- Teams documenting how their builds and deployments run
How to Use the GitHub Actions Workflow Visualizer
Paste a workflow, check the graph, and fix anything flagged before pushing.
Paste the Workflow File
Copy a file from .github/workflows, such as ci.yml, into the box. Steps, env and permissions can stay; they just aren’t drawn.
Read the Graph
The rounded node lists the triggers, and arrows run from each job to the jobs that need it. Jobs side by side run at the same time on separate runners.
Fix What’s Flagged
If a needs entry names a missing job, or jobs need each other in a loop, the error names them. Correct the YAML and the graph redraws.
Copy the Mermaid Source
Switch to Mermaid source and paste it into Markdown inside a mermaid code block to document the pipeline in your repository.
Workflows and the Graphs They Make
Each answer is the Mermaid source this visualizer produced for the workflow on the left, or the error it reported. Sketch the job order in your head before revealing it.
“on: push jobs: test: runs-on: ubuntu-latest build: needs: test runs-on: ubuntu-latest”
“on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest test: runs-on: ubuntu-latest deploy: needs: [lint, test] runs-on: ubuntu-latest”
“on: push jobs: test: runs-on: ${{ matrix.os }} strategy: matrix: os: [ubuntu-latest, macos-latest] node: [20, 22]”
“on: push jobs: build: runs-on: ubuntu-latest deploy: needs: build if: github.ref == 'refs/heads/main' uses: acme/infra/.github/workflows/deploy.yml@v2”
“on: release: types: [published] workflow_dispatch: jobs: publish: runs-on: [self-hosted, linux, x64]”
“on: push jobs: unit: name: Unit tests runs-on: ubuntu-latest e2e: name: End-to-end tests needs: unit runs-on: ubuntu-latest”
“on: push jobs: build: runs-on: ubuntu-latest needs: setup”
“on: push jobs: a: runs-on: ubuntu-latest needs: b b: runs-on: ubuntu-latest needs: a”
“on: push jobs: build: steps: - run: make”
“on: push jobs: 2build: runs-on: ubuntu-latest”
The Workflow Keys Behind the Graph
The diagram is built from a handful of keys in GitHub’s workflow syntax. This is what each one does.
on
The events that start the workflow, such as push, pull_request, schedule or workflow_dispatch. It can be one event, a list or a map with filters.
“Which event lets you start a workflow by hand?”
jobs
The map of jobs, keyed by job ID. Without needs, every job starts at the same time on its own runner.
“Do jobs run one after another by default?”
needs
A job ID or list of IDs that must succeed before this job starts. If one fails, dependent jobs are skipped unless their condition says otherwise.
“What happens to a job when a job it needs fails?”
runs-on
The runner for the job: a GitHub-hosted label like ubuntu-latest, a list of self-hosted labels, or a runner group.
“What does runs-on: [self-hosted, linux] select?”
uses at the Job Level
Calls a reusable workflow instead of running steps, written as owner/repo/.github/workflows/file.yml@ref. Such jobs have no runs-on.
“Does a job that calls a reusable workflow need runs-on?”
strategy.matrix
Runs the job once per combination of values. Two operating systems and two Node versions make four runs of one job.
“How many runs does a 2 by 3 matrix create?”
if
A condition that decides whether the job runs, often on the branch or event. success(), failure() and always() change how needs failures are handled.
“Which function runs a job even if a needed job failed?”
Job IDs
IDs must start with a letter or underscore and use only letters, digits, dashes and underscores. needs refers to IDs, not display names.
“Can needs refer to a job’s name field?”
name
An optional display name shown in the Actions tab and in the diagram. It can contain spaces and expressions.
“Does changing a job’s name break its needs?”
outputs
Values a job passes to jobs that need it, read as needs.job.outputs.name. Only jobs listed in needs can read them.
“Can a job read outputs from a job it doesn’t need?”
How GitHub Orders Jobs
The diagram is the dependency graph GitHub schedules from. These rules explain what happens at run time.
Independent Jobs Run Together
Jobs without needs start at once, each on a fresh runner, limited only by your plan’s concurrent job limit.
A Needed Job Must Succeed
A job waits until every job it needs has finished successfully. A failure or skip upstream skips it unless its if uses always() or failure().
Matrix Runs Count as One Job
A job that needs a matrix job waits for every combination to finish. With fail-fast on, one failing combination cancels the rest.
Reusable Workflows Expand Inline
A job that uses a reusable workflow runs that workflow’s own jobs, which appear in the Actions tab under the calling job.
Runners Don’t Share Files
Each job starts on a clean machine. Pass build results between jobs with artifacts or caches, not the filesystem.
Concurrency Groups Can Cancel Runs
A concurrency key at the workflow or job level cancels or queues overlapping runs, which the graph doesn’t show.
Workflow Graph Mistakes
These are the usual reasons jobs run in the wrong order, or not at all.
Using the Display Name in needs
needs: Unit tests fails when the job ID is unit. Always refer to the ID under jobs.
Forgetting needs on a Deploy Job
Without needs, deploy starts at the same time as test and can ship broken code. Make it need every check.
Assuming Files Carry Over
A later job can’t see files the build job wrote. Upload them with actions/upload-artifact and download them where needed.
Skipped Jobs Skipping Everything After
When a needed job is skipped by its own if, dependent jobs are skipped too. Add an if with always() or a success check to override it.
Long Serial Chains
Jobs that need each other in a long line run one at a time. Let independent checks such as lint and test run in parallel.
Tabs in YAML
Workflow YAML must be indented with spaces. A tab breaks the file, and GitHub shows it as an invalid workflow.
A Mistyped on Key
Writing push under jobs instead of on, or misspelling pull_request, means the workflow never triggers. The trigger node shows what was read.
Huge Matrices
Each dimension multiplies the job count, and a matrix tops out at 256 jobs per workflow run. Use include and exclude to trim combinations.
Common Pipeline Shapes
Most workflows follow one of these shapes. Paste yours to see which, and whether the needs match the intent.
Fan-Out, Fan-In
Independent checks such as lint, test and type-check run in parallel, then one job needs all of them. It’s the fastest shape for pull request checks.
Build Once, Deploy Many
A single build job uploads an artifact, and deploy jobs for staging and production need it. Production often also needs staging.
Matrix Then Summary
A matrix job tests every combination, and a summary job needs it to post one combined result. Branch protection can require just the summary.
Gated Release
Publish jobs need the build and run only on tags or release events, using an if condition. An environment with required reviewers adds a manual approval.
Reusable Workflow Calls
Shared CI or deploy logic lives in one reusable workflow, and many repositories call it with uses. Each call appears as a single job here.
Scheduled Maintenance
A schedule trigger runs dependency updates or cleanup jobs nightly, often alongside workflow_dispatch so it can be run by hand.
When a Workflow Graph Helps
Whenever a pipeline is too long to hold in your head.
Reviewing a Workflow Change
Paste the workflow from a pull request to confirm that a new job waits for the right checks.
Speeding Up CI
Spot long chains of jobs that could run in parallel, and reorder needs to shorten the critical path.
Documenting a Pipeline
Copy the Mermaid source into CONTRIBUTING.md so new contributors see how builds and releases flow.
Debugging a Skipped Job
Trace which upstream job a skipped job depends on, then check that job’s if condition and result.
Migrating From Another CI System
After converting a Jenkins or GitLab pipeline, compare the new job graph with the old stages.
Checking a Release Workflow
Make sure publishing jobs only run after builds pass, and only for release events.
Learning GitHub Actions
Edit needs and triggers and watch the graph change, which makes parallel and sequential jobs click.