# Kesin11/actions-timeline: Mermaid Gantt Charts for GitHub Actions Runs

> A GitHub Action that reads a workflow run back from the API and draws a mermaid gantt timeline into the run summary. Useful for spotting which job or step ate the clock, with real limits around permissions, post-processing order and GHES versions.

**Kesin11/actions-timeline** — An Action shows timeline of a workflow in a run summary.

- Repository: https://github.com/Kesin11/actions-timeline
- Stars: 335 · Forks: 8
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/kesin11-actions-timeline

## What actions-timeline solves, and for whom

GitHub shows you each job and step in a run, but it shows them as a list. To answer "why did this run take 14 minutes" you open jobs one at a time and compare timestamps by eye. actions-timeline compresses that into one picture: it fetches the jobs and steps of a workflow run from the GitHub API and generates a timeline as a mermaid gantt diagram, which GitHub flavored markdown renders directly in the run summary page. The README frames the goal as identifying "issues or bottlenecks in your workflow".

The audience is narrow and specific. This is for people who own a CI workflow and are already looking at run summaries, not for people who want fleet-wide CI analytics. The README's own advice points at the shape of that audience: if your workflow has many jobs, run the action in the job that takes the most time, or add an independent job at the end of the workflow that depends on the others. That is a manual placement decision, and it tells you the tool is designed for per-run inspection rather than aggregation.

## How the timeline is built from the GitHub API

There is no instrumentation step and no tracing agent. The action runs at the end of a job, calls the GitHub API for the workflow run's jobs and steps, and turns the returned timestamps into mermaid gantt syntax. That is the whole data flow: API in, markdown out, rendered by GitHub's markdown pipeline.

Two features go beyond a flat bar chart. Steps declared with the GitHub Actions parallel syntax are detected automatically; the timeline keeps the Parallel group bar and adds (bg) rows for its child steps at their actual shared start time, and the README states that this detection is verified against the job log. Repo-local composite actions can be expanded with expand-composite-actions: true, which keeps the original composite bar and adds (sub) rows for its internal steps. Nested repo-local composite actions are not currently expanded, and the CLI adds a threshold option so you can expand only composite actions that take more than a given number of seconds.

The placement rule matters more than it looks. The action executes during the job's post-processing, so it must be registered before your build step. Register it after, and the README says the timeline will not include other post-processing steps. This is a real ordering constraint, not a style preference.

## Installing actions-timeline and reading your first run summary

There is nothing to install locally. You add the action to a workflow. The README's minimal example registers it before the build step so it runs at the end of the job post-processing, and shows the github-token input defaulting to ${{ github.token }} plus a show-waiting-runner toggle that defaults to true.

```yaml
jobs:
  build:
    runs-on: ubuntu-slim
    steps:
      # Register this action before your build step. It will then be executed at the end of the job post-processing.
      - uses: Kesin11/actions-timeline@v2
        with:
          # e.g.: ${{ secrets.MY_PAT }}
          # Default: ${{ github.token }}
          github-token: ""
          # Show waiting runner time in the timeline.
          # Default: true
          show-waiting-runner: true
```

After the run finishes, open the run summary page. The mermaid gantt chart appears there. If the action fails to fetch jobs and steps, the README says you may need to grant the actions:read permission explicitly:

```yaml
jobs:
  build:
    permissions:
      actions: read
    runs-on: ubuntu-slim
    steps:
      - uses: Kesin11/actions-timeline@v2
```

If you prefer to generate the markdown outside a workflow, the repository ships cli.ts and the README runs it through Deno, taking a run URL, a token and an output file:

```bash
deno run --allow-net --allow-write --allow-env=GITHUB_API_URL \
  https://raw.githubusercontent.com/Kesin11/actions-timeline/main/cli.ts \
  https://github.com/Kesin11/actions-timeline/actions/runs/8021493760/attempts/1 \
  -t $(gh auth token) \
  -o output.md
```

The README notes that cli.ts only writes markdown to a file or STDOUT, so visualizing it is your problem: the Mermaid Live Editor, VS Code's markdown preview (which supports mermaid diagrams since 1.121 according to the README), or mermaid-cli in a terminal.

## Permissions, post-processing order and GHES version gaps

The known issues section is where the sharp edges are. The first is permissions: in some cases the workflow needs actions:read to fetch workflow jobs and steps, and the README shows the error case and the job-level permissions block that fixes it. If your workflow already sets a restrictive permissions block, expect to add it, and note that the README says "in some cases", not always, so you may not discover the need until a run fails.

The second is version-dependent behaviour on GitHub Enterprise Server. The GET workflow_job API response does not contain the created_at field in GHES v3.8; it was added in v3.9. Without that field, the elapsed time a runner spends waiting for a job cannot be calculated, so actions-timeline omits the Waiting for a runner step from the timeline. On GHES v3.8 you get a chart that is quietly missing a row, not an error. That is the kind of silent degradation worth knowing before you compare two timelines.

GHES support itself is handled through the GITHUB_API_URL environment variable. The README's point is that GitHub Actions sets its default environment variables for you, so no code change is required to point the action at your enterprise instance.

## What actions-timeline does not do

It draws one run. There is no history, no trend line, no comparison between runs, and no aggregation across workflows. If a job has been slow for three weeks, this action will show you today's slow job and nothing about the pattern.

The mermaid output is also a rendering dependency. In a run summary, GitHub handles that for you. Everywhere else it does not, which is why the CLI section of the README spends its time pointing at the Mermaid Live Editor, VS Code and mermaid-cli rather than at the tool itself. If your destination cannot render mermaid, the CLI output is a markdown file of gantt syntax you cannot read.

Finally, the composite expansion has a stated boundary: nested repo-local composite actions are not currently expanded, and only repo-local composites are covered at all. Teams that lean heavily on published composite actions from other repositories will see less detail than the feature name suggests.

A note on maintenance: the last push to the repository was on 2026-08-01, and the most recent release is v3.2.0 on the same date, following v3.1.1 on 2026-07-01 and v3.1.0 on 2026-04-18.

## Where it sits next to OpenTelemetry-based CI tracing

The README lists three similar works: Kesin11/github_actions_otel_trace, inception-health/otel-export-trace-action and runforesight/workflow-telemetry-action. The difference in approach is the interesting part. Those projects export OpenTelemetry traces, which means the timing data leaves the run and lands in a tracing backend where you can query across runs, correlate with other services and keep history. actions-timeline does the opposite: it reads the run back from the GitHub API and renders it inside the run summary, so nothing is exported and nothing is retained beyond the summary itself.

That makes actions-timeline the lighter option and the more limited one. If your question is "what happened in this specific run", the gantt chart in the summary answers it with no backend to run. If your question is "which workflow is getting slower over the quarter", an OpenTelemetry export is the shape of tool that can answer it, because the data persists somewhere you can query. Choosing actions-timeline for trend analysis is choosing the wrong tool.

## Conclusion

Adopt it if you already read run summaries and want job and step durations drawn as a gantt chart without shipping logs anywhere. Do not adopt it if you need per-run cost accounting, if you are on GHES below v3.9 and expect a runner-wait row, or if your workflow cannot grant actions:read. Before rollout, run the action once on a multi-job workflow with a job-level permissions block, confirm the summary renders, and check whether your composite actions need expand-composite-actions: true and a threshold.

## FAQ

### Where should I place Kesin11/actions-timeline in my workflow steps?

Register it before your build step, because the action runs during the job's post-processing. The README warns that if you register it after the build step, the timeline will not include other post-processing steps.

### Why does actions-timeline ask for actions:read permission?

It fetches workflow jobs and steps from the GitHub API, and the README states that in some cases the workflow needs actions:read to do so. The README shows the error case and a job-level permissions block with actions: read as the fix.

### Can I use actions-timeline on GitHub Enterprise Server?

Yes. It works on GHES through the GITHUB_API_URL environment variable, which GitHub Actions sets by default. On GHES below v3.9 the workflow_job API response lacks created_at, so the Waiting for a runner step is omitted from the timeline.

### Can I run actions-timeline outside a GitHub Actions workflow?

Yes, the repository ships cli.ts and the README runs it with deno run against a run URL, taking a token and an output file. The README notes that cli.ts only outputs markdown, so you need another tool to visualize the mermaid diagram.

## Sources

- [Official README](https://github.com/Kesin11/actions-timeline#readme)
- [Project repository](https://github.com/Kesin11/actions-timeline)
- [Release notes](https://github.com/Kesin11/actions-timeline/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kesin11-actions-timeline