actions-timeline 评测：把 GitHub Actions 运行历史画成时间线

它解决什么问题

GitHub Actions 的默认日志页面按 job 和 step 排列，但很难一眼看出哪个步骤耗时最长，或者整个工作流的时间花在了哪里。actions-timeline 把每次运行的 job 和 step 时间数据拉取下来，渲染成 Mermaid 甘特图，直接显示在 run summary 页面。它的目标用户是维护复杂工作流的开发者，尤其是那些需要向团队解释构建耗时构成的人。它不提供实时监控，也不做历史趋势分析，只负责把一次运行的时间线画出来。

工作机制：从 API 到甘特图

actions-timeline 在 job 的 post 阶段执行。它通过 GitHub API 获取当前 workflow run 的 jobs 和 steps 数据，包括每个 step 的开始和结束时间。然后生成 Mermaid gantt 图，利用 GitHub 对 Mermaid 的原生支持，把图嵌入 run summary。关键点在于，它必须注册在 build step 之前，因为 post 阶段只包含注册位置之前的步骤。如果放在 build 之后，时间线就会缺少后续的 post-processing 步骤。对于并行步骤，它自动检测 GitHub Actions 的 parallel 语法，保留 Parallel group 条，并为每个子步骤添加 (bg) 行，这些子步骤的开始时间取自 job 日志。

配置与运行方式

在 workflow 中添加一个 step 即可，最简单的用法是：uses: Kesin11/actions-timeline@v2，并放在需要跟踪的 job 里。可选参数包括 github-token（默认是 ${{ github.token }}），以及 show-waiting-runner（默认 true），用于显示等待 runner 的时间。如果你的工作流有多个 job，README 建议把该 Action 放在耗时最长的 job 中，或者创建一个独立的 job，用 needs 依赖其他 job。独立 job 的写法是：jobs: actions-timeline: needs: [build-1, build-2, build-3] runs-on: ubuntu-slim steps: - uses: Kesin11/actions-timeline@v2。此外，它还有一个 CLI 工具，可以用 deno run 直接执行，输出 markdown 文件，再用 Mermaid Live Editor 或 VSCode 预览。

复合 Action 的展开能力

从 v3.x 开始，actions-timeline 支持展开仓库内的复合 Action。设置 expand-composite-actions: true 后，时间线会保留原始的复合条，并在其下方显示内部步骤，行名带 (sub) 后缀。CLI 工具还支持 --expand-composite-actions-threshold 参数，只展开耗时超过指定秒数的复合 Action。这是一个实用的功能，因为复合 Action 常常掩盖内部步骤的耗时。但要注意，嵌套的复合 Action 目前不会被展开，也就是说，如果复合 Action 内部又调用了另一个复合 Action，内部细节仍然不可见。这是一个明确的边界，如果你有深层次的复合结构，需要自行评估是否够用。

已知限制与失败模式

README 明确列出两个已知问题。第一，某些情况下工作流需要 actions: read 权限，否则 API 调用会失败。所以你需要显式声明 permissions: actions: read。第二，在 GHES v3.8 及以下版本，workflow_job API 响应中没有 created_at 字段，因此无法计算 'Waiting for a runner' 的时间，该步骤会被省略。这意味着如果你在旧版 GHES 上运行，时间线会缺失等待时间，可能误导你对瓶颈的判断。另外，该 Action 只在 job 结束时运行，所以它无法捕捉到 job 被取消或超时的情况，因为 post 阶段可能不会执行。

替代方案与差异

README 列出了三个类似项目：Kesin11/github_actions_otel_trace、inception-health/otel-export-trace-action 和 runforesight/workflow-telemetry-action。其中 github_actions_otel_trace 是同一个作者的项目，它把工作流事件导出为 OpenTelemetry trace，适合接入现有的可观测性基础设施。otel-export-trace-action 也做类似的事，但更侧重于将 trace 发送到 OpenTelemetry Collector。runforesight 则是一个商业化的工作流分析平台，提供更丰富的仪表盘和趋势分析。与之相比，actions-timeline 的差异在于：它不依赖外部服务，数据直接显示在 GitHub 页面内，部署成本几乎为零。但代价是它没有历史记录，也不提供聚合视图。

维护与升级成本

项目采用 MIT 许可证，你可以自由修改和分发。最近一次提交在 2026 年 8 月，v3.2.0 是当前版本，说明维护活跃。升级成本主要来自 GitHub API 的变化，例如 created_at 字段的引入，以及 Mermaid 语法兼容性。由于它依赖 GitHub 的 Mermaid 渲染，如果 GitHub 升级 Mermaid 版本，可能导致图表语法不兼容。从仓库布局看，它使用 deno 进行开发，并需要生成 dist/ 目录才能作为 Action 使用。如果你要修改源码，需要先运行 deno task bundle 重新打包。整体而言，维护成本不高，但你需要留意 GitHub API 的变更，特别是 GHES 版本差异。

编辑结论

如果你经常为多 job 工作流的耗时分布发愁，或者需要向同事展示某次运行中等待 runner 的时间占比，actions-timeline 值得一试。它适合那些已经习惯在 run summary 页面里看结果、不想额外搭建仪表盘的团队。不适合的场景是：你需要实时监控或历史趋势统计，因为该 Action 只在 job 结束时生成一张静态图。也不适合需要展开嵌套复合 Action 的复杂流程，当前版本只支持一层展开。在采纳前，先确认你的 GitHub 版本是否支持 workflow_job API 的 created_at 字段（GHES 需 v3.9 以上），并在工作流中显式声明 permissions: actions: read，否则可能遇到 403 错误。另外，若你的工作流包含大量并行步骤，注意时间线会为每个并行子步骤增加一行，图表可能变得很长。

官方来源

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