# actions-timeline

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Kesin11/actions-timeline)

An Action shows timeline of a GitHub Action workflow in the run summary page.

`actions-timeline` is a tool that allows developers to visualize the sequence of
jobs and steps that occur during a GitHub Actions workflow. By examining the
timeline, you can quickly identify any issues or bottlenecks in your workflow,
and make adjustments as needed to improve performance and efficiency.

![Sample screenshot workflow](https://github.com/user-attachments/assets/03353645-ec6f-4fd6-80b5-19694439393f)
![Sample screenshot timeline](https://github.com/user-attachments/assets/d92027fc-ded2-4b6e-9ab0-e3923b698ec3)

## USAGE

```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
          # Expand repo-local composite action steps in the timeline while
          # keeping the original composite bar and showing expanded sub-steps
          # beneath it.
          # Note: This option requires additional API calls to fetch job logs
          # and workflow files, which may increase execution time.
          # Limitation: Composite actions that contain nested local composite
          # actions (uses: ./.github/actions/...) are not expanded.
          # Default: false
          expand-composite-actions: false
          # Duration threshold in seconds for expanding composite action steps.
          # Only steps at or above this duration are expanded.
          # Default: 20
          expand-composite-actions-threshold: 20

      # Your build steps...
```

If your workflow has many jobs, you should run `actions-timeline` in the job
that takes the most time, or create an independent job for `actions-timeline` in
a last of the workflow.

```yaml
jobs:
  build-1:
  build-2:
  build-3:

  actions-timeline:
    needs: [build-1, build-2, build-3]
    runs-on: ubuntu-slim
    steps:
      - uses: Kesin11/actions-timeline@v2
```

## How it works

`actions-timeline` fetches the jobs and steps of the workflow run from the
GitHub API, and then generates a timeline with
[mermaid gantt diagrams](https://mermaid.js.org/syntax/gantt.html). Thanks to
the GitHub flavored markdown that can visualize mermaid diagrams, the timeline
is displayed in the run summary page.

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. Detection is verified
against the job log.

Repo-local composite actions can also be expanded by setting
`expand-composite-actions: true`. The original composite bar remains visible,
with its internal steps shown as `(sub)` rows beneath it. Nested repo-local composite actions are not currently expanded.

This action is run on post-processing of the job, so you should register this
action before your build step. If you register this action after your build
step, the timeline will not include other post-processing steps.

## Support GHES

`actions-timeline` can also work on GitHub Enterprise Server(GHES). It needs
`GITHUB_API_URL` environment variable to access your GHES. Thanks to GitHub
Actions, it sets
[default environment variables](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables)
so you do not need to make any code changes.

## Known issues

> [!IMPORTANT]
> **In some cases, the workflow requires `actions:read' permission.**

Sometimes the
`actions:read' permission is needed in the workflow to fetch workflow jobs and steps. If you see the following error, you need to add the`actions:read'
permission to your workflow.

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

> [!IMPORTANT]
> **'Waiting for a runner' step is not supported < GHES v3.9**

GET `workflow_job` API response does not contain `created_at` field in
[GHES v3.8](https://docs.github.com/en/enterprise-server@3.8/rest/actions/workflow-jobs#get-a-job-for-a-workflow-run),
it is added from
[GHES v3.9](https://docs.github.com/en/enterprise-server@3.9/rest/actions/workflow-jobs?apiVersion=2022-11-28).
So it is not possible to calculate the elapsed time the runner is waiting for a
job, `actions-timeline` omits `Waiting for a runner` step in the timeline.

# Similar works

- https://github.com/Kesin11/github_actions_otel_trace
- https://github.com/inception-health/otel-export-trace-action
- https://github.com/runforesight/workflow-telemetry-action

# CLI tool

`actions-timeline` is also available as a CLI tool. You can use it with
`deno run` command.

```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

# Fetch latest attempt if ommit attempts
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/ \
  -t $(gh auth token) \
  -o output.md

# GHES
deno run --allow-net --allow-write --allow-env=GITHUB_API_URL \
  https://raw.githubusercontent.com/Kesin11/actions-timeline/main/cli.ts \
  https://YOUR_ENTERPRISE_HOST/OWNER/REPO/actions/runs/RUN_ID/attempts/1 \
  -t $(gh auth token -h YOUR_ENTERPRISE_HOST) \
  -o output.md
```

```bash
# Expand composite action steps while keeping the parent composite bar
deno run --allow-net --allow-write --allow-env=GITHUB_API_URL \
  https://raw.githubusercontent.com/Kesin11/actions-timeline/main/cli.ts \
  https://github.com/OWNER/REPO/actions/runs/RUN_ID \
  -t $(gh auth token) \
  --expand-composite-actions true \
  -o output.md
```

```bash
# Expand composite actions that take more than 10 seconds
deno run --allow-net --allow-write --allow-env=GITHUB_API_URL \
  https://raw.githubusercontent.com/Kesin11/actions-timeline/main/cli.ts \
  https://github.com/OWNER/REPO/actions/runs/RUN_ID \
  -t $(gh auth token) \
  --expand-composite-actions true \
  --expand-composite-actions-threshold 10 \
  -o output.md
```

`cli.ts` just outputs the markdown to file or STDOUT, so you have to use other
tools to visualize mermaid diagrams.

- Online editor:
  [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/)
- VSCode natively supports Mermaid diagrams in Markdown preview and notebooks
  since 1.121:
  [release notes](https://code.visualstudio.com/updates/v1_121#_mermaid-diagrams-in-markdown-preview-and-notebooks)
- Local terminal: [mermaid-cli](https://github.com/mermaid-js/mermaid-cli)

# DEVELOPMENT

## Setup

```
asdf install
deno task setup:githooks
```

# DEBUG

If you want to debug this action, first generate `dist/` then execute own
action.

```yaml
- uses: actions/checkout@v3
- uses: denoland/setup-deno@v1
- run: deno task bundle
- uses: ./
```

# LICENSE

MIT