actions-timeline: Visualizing GitHub Actions Workflow Runs as Mermaid Gantt Charts

What Problem This Solves and Who It Is For

GitHub Actions run summary pages show job outcomes and logs, but they do not give you a quick sense of where time goes inside a workflow. actions-timeline fills that gap by generating a timeline of jobs and steps and displaying it on the run summary page. The target user is a developer or maintainer who wants to spot slow steps, waiting time, or parallelization issues without leaving the GitHub UI. The README positions it as a way to identify bottlenecks and adjust workflows. It is not a monitoring or alerting tool; it is a visualization aid that works on demand for each run.

How the Timeline Is Generated: GitHub API and Mermaid

The action works by fetching the jobs and steps of the current workflow run from the GitHub API. It then generates a Mermaid gantt diagram. Because GitHub flavored markdown supports Mermaid rendering in run summaries, the diagram appears directly on the summary page. The README explains that steps declared with the GitHub Actions parallel syntax are detected automatically. The timeline keeps a Parallel group bar and adds (bg) rows for child steps at their actual shared start time. Detection is verified against the job log. This mechanism is straightforward: it reads run data, transforms it into a gantt chart, and posts it as part of the summary. The action runs in the post-processing phase of a job, which is why placement matters.

Getting It Running: Setup and Configuration

To use it, add a step with uses: Kesin11/actions-timeline@v2 before your build step. The README example shows a job with runs-on: ubuntu-slim and a step that uses the action. The key inputs are github-token, which defaults to ${{ github.token }}, and show-waiting-runner, which defaults to true. You can also set expand-composite-actions: true to expand repo-local composite action steps. The action must be registered before your build step, otherwise the timeline will not include other post-processing steps. For workflows with many jobs, the README recommends running actions-timeline in the job that takes the most time, or creating a separate job that depends on all other jobs. That separate job approach is shown with needs: [build-1, build-2, build-3].

Handling Parallel Steps and Composite Actions

A notable feature is the automatic detection of parallel steps. GitHub Actions introduced a parallel syntax, and actions-timeline preserves the Parallel group bar while adding (bg) rows for child steps at their actual shared start time. The README states that detection is verified against the job log. For composite actions, setting expand-composite-actions: true expands repo-local composite action steps. The original composite bar remains visible, and internal steps appear as (sub) rows beneath it. However, nested repo-local composite actions are not expanded. This is a clear limitation: if your composite actions contain their own composite actions, you will only see one level of expansion. The CLI tool offers a threshold option, --expand-composite-actions-threshold, to only expand composite actions that take longer than a specified number of seconds, which can keep the diagram from getting cluttered.

Known Limitations and Failure Modes

The README documents two important issues. First, in some cases the workflow requires the actions:read permission to fetch workflow jobs and steps. If you see an error, you must add permissions: actions: read to the job. This is a common gotcha because many workflows do not explicitly set permissions. Second, the Waiting for a runner step is not supported on GitHub Enterprise Server versions below 3.9. The GET workflow_job API response does not contain the created_at field in GHES v3.8, so the action cannot calculate the elapsed time a runner waits for a job. In that case, actions-timeline omits the Waiting for a runner step entirely. This means on older GHES instances you lose visibility into queue time, which is often the biggest bottleneck. Another practical limitation is that the action only runs in post-processing, so if you place it after your build step, it will not capture other post-processing steps. That is a placement constraint that can lead to incomplete timelines if misconfigured.

CLI Tool and Alternative Ways to View the Timeline

Beyond the GitHub Action, actions-timeline is also available as a CLI tool that runs with deno run. The README shows commands like deno run --allow-net --allow-write --allow-env=GITHUB_API_URL https://raw.githubusercontent.com/Kesin11/actions-timeline/main/cli.ts <run-url> -t $(gh auth token) -o output.md. The CLI fetches the run and outputs markdown to a file or STDOUT. It does not visualize the diagram itself; you need another tool to render the Mermaid diagram. The README suggests the Mermaid Live Editor, VSCode's native Mermaid preview (since version 1.121), or mermaid-cli for local terminal use. This CLI is useful for generating timelines outside of GitHub, for example in CI logs or local debugging. It also supports GHES via the GITHUB_API_URL environment variable, which GitHub Actions sets by default, so no code changes are needed.

Comparing with Alternatives: OTel Traces and Workflow Telemetry

The README lists three similar works: Kesin11/github_actions_otel_trace, inception-health/otel-export-trace-action, and runforesight/workflow-telemetry-action. These alternatives take a different approach: they export workflow data to OpenTelemetry or a telemetry platform, which allows for aggregated metrics, custom dashboards, and historical analysis. actions-timeline is simpler: it renders a one-off timeline in the run summary, with no external dependencies or data storage. If you need to track performance trends over time or integrate with your observability stack, an OTel exporter is more appropriate. If you just want a quick visual of a single run, actions-timeline is lighter and requires no additional infrastructure. The trade-off is that you lose the ability to query historical data or set alerts. The choice depends on whether you need persistent telemetry or a quick glance.

Maintenance, Upgrade Cost, and License

The repository is written in TypeScript and licensed under MIT. The most recent release is v3.2.0, pushed on 2026-08-01, with prior releases in July and April of the same year. This suggests active maintenance. The README shows usage with @v2, but the latest release is v3.2.0, so you should check the release notes for breaking changes when upgrading. The action is distributed as a GitHub Action, so maintenance cost is low: you just update the version tag in your workflow. The CLI tool requires Deno, which is a runtime you may need to install if you use it outside of GitHub Actions. The MIT license allows free use and modification, but you should review the license file for any conditions. There is no mention of a dedicated support channel, so you rely on GitHub issues. The development setup uses asdf and deno task setup:githooks, which is typical for a Deno-based project.

Editorial conclusion

Adopt actions-timeline if you need a quick, dependency-free visual of job and step durations directly in the GitHub run summary page, especially for workflows with parallel steps or repo-local composite actions. Skip it if you require detailed traces, metrics aggregation, or support for GHES versions below 3.9 where waiting-runner time is unavailable. Before adopting, verify that your workflow has the required actions:read permission and that you place the action before your build steps to capture post-processing steps. Test the composite expansion on a sample workflow to confirm it meets your needs, as nested composite actions are not expanded.

Official sources

1. Official README
2. Project repository
3. Release notes