ghaperf - GitHub Actions の log から本当に遅い step を見つける CLI

GitHub Actions が遅くなったとき、最初に見えるのは「この job が十数分かかった」という大きな単位です。しかし実際に改善する段階では、その粒度だけでは足りません。遅いのは checkout なのか、dependency install なのか、cache restore なのか、composite action なのか、それとも script 内の一部なのか。Workflow run の合計時間だけを見ると、最初に直すべき場所を間違えやすくなります。

今日紹介する suzuki-shunsuke/ghaperf は、この細かい観測に向いた tool です。Go で書かれた command line tool で、GitHub API から workflow run、job、raw job log を取得し、log から step と log group の duration を解析して Markdown report を出します。GitHub search result では現在およそ 32 stars、0 forks。主な言語は Go、license は MIT です。Repository は 2025 年 10 月 26 日に作成され、2026 年 5 月 29 日にも更新されています。README と tag 情報では最新 version は v0.1.1 です。

プロジェクト概要

項目	内容
リポジトリ	suzuki-shunsuke/ghaperf
Stars	約 32
Forks	0
主な言語	Go
ライセンス	MIT
作成日	2025 年 10 月 26 日
最近の更新	2026 年 5 月 29 日
最新 release	v0.1.1

CI performance を step level まで分解する

ghaperf の価値は、GitHub Actions の画面を置き換えることではありません。「どこが遅いか」をより細かく分解することです。README が強調しているのは、job log を解析することで composite action の内部 bottleneck を見つけられる点です。多くの Actions performance tool は job や step の timeline を見せられますが、composite action は一つの大きな step として見えがちです。その step の中で tool install、dependency download、script execution が行われていると、実際に遅い部分が分かりません。

ghaperf は raw log の timing information を読み、threshold を超えた slow step をまとめます。GitHub Actions の log group にも対応しています。Action や script が ::group:: / ::endgroup:: で内部処理を分けていれば、ghaperf はその group の duration も見られます。

これは CI を保守する人にとって実用的です。Pipeline は一つの明らかな command だけで遅くなるとは限りません。Cache miss、installer の再 download、特定 runner の初期化、matrix の一部だけが外れ値になる、といった小さな遅さが積み重なります。Job log を一つずつ開いて timestamp を読むより、まとめた report のほうが判断しやすいです。

三つの分析入口

ghaperf にはいくつかの entry point があります。

もっとも自然なのは、workflow の複数 run を分析する mode です。

ghaperf \
  --repo suzuki-shunsuke/ghaperf \
  --workflow test.yaml \
  --count 10 \
  --threshold 2s

この mode は安定した bottleneck を探すのに向いています。一回の CI は network、runner scheduling、cache status の影響を受けます。最近 10 回や 100 回の run を見ることで、ある step が常に遅いのか、たまたま遅かっただけなのかを判断しやすくなります。

二つ目は単一の workflow run を分析する方法です。

ghaperf \
  --repo suzuki-shunsuke/tfaction \
  --run-id "<workflow run id>"

これは特定の失敗や異常に遅い build を調べるときに便利です。三つ目は job id を指定する方法です。

ghaperf \
  --repo suzuki-shunsuke/tfaction \
  --job-id "<workflow job id>"

GitHub の画面で問題の job まで絞れているなら、この入口が一番直接的です。さらに --log-file で local に保存した job log も分析できます。Parser の挙動を確認したり、GitHub API を繰り返し呼ばずに再現したりする用途に合います。

Markdown report は PR や issue に貼りやすい

ghaperf の output は Markdown report です。Report には分析対象、threshold、workflow run 数、各 job の average duration、slowest job link、slow step の aggregate が並びます。README の例では、同じ種類の job をまとめ、Run aqua i --test、rustup update、actions/checkout のような slow point を列挙しています。

この format は team discussion に向いています。CI 改善では、まず「感覚で遅いと言っているのではなく、最近 N 回の run でこの phase が平均これだけ時間を使っている」と共有する必要があります。Markdown なら PR、issue、Slack、内部 document にそのまま貼れます。各 job への link も残るので、根拠を追いやすいです。

Automation にも使いやすいです。長く動かす Web service ではなく、metrics database も必要ありません。Local や CI で必要なときに実行し、report を artifact や comment として出せます。小さな team にとって、この一回実行型の診断 tool は維持コストが低いです。

設定：job name の filtering と normalization

GitHub Actions の matrix job name は長くなりがちで、parameter の違いによって同じ種類の task が別 job に見えます。ghaperf は config file でこの問題を扱います。

Config は ghaperf --init で生成できます。主な field は次の通りです。

job_names:
  - "test / test / test .*"

excluded_job_names:
  - "experimental .*"

job_name_mappings:
  "test / test / test .*": "test / test / test"

job_names は分析対象 job の絞り込み、excluded_job_names は除外、job_name_mappings は matrix や rename された job を同じ名前にまとめるために使います。Project には JSON Schema もあり、editor で completion と validation を有効にできます。

この設定は地味ですが、CI performance analysis では重要です。Filtering がなければ report は関係ない job で埋まります。Normalization がなければ、同じ test pipeline が OS や parameter ごとに分散して、全体の傾向を見にくくなります。

Metrics storage は不要、ただし token は必要

ghaperf の特徴の一つは、backend が不要なことです。GitHub API と job log をその場で読んで分析するため、Prometheus、BigQuery、OpenTelemetry collector、自前 database を先に用意する必要がありません。一度だけ bottleneck を調べたい user にとって、この入口は軽いです。

一方で GitHub access token は必要です。README は、public repository でも action logs を download するには token が必要だと説明しています。Private repository では少なくとも Actions: Read permission が必要です。Token は GITHUB_TOKEN または GHAPERF_GITHUB_TOKEN から読めます。作者の別 tool である ghtkn integration もあります。

また、completed workflow run と job の API response は cache されます。Default location は ${XDG_CACHE_HOME:-${HOME}/.cache}/ghaperf/ です。同じ run を何度も分析するとき、API call と待ち時間を減らせます。

Installation は CLI user 向け

ghaperf は Go project なので、binary を PATH に置けば使えます。Official docs には Homebrew、aqua、GitHub Releases、go install が載っています。

brew install suzuki-shunsuke/ghaperf/ghaperf --cask

aqua g -i suzuki-shunsuke/ghaperf

go install github.com/suzuki-shunsuke/ghaperf/cmd/ghaperf@latest

Official binary support は Linux amd64/arm64 と macOS arm64 です。他の platform は source から build できます。Release asset については GitHub CLI、slsa-verifier、Cosign での verification 手順も書かれています。CI performance を気にする user にとって、supply chain verification の説明があるのは好印象です。

向いている場面

ghaperf はかなり具体的な場面に向いています。

GitHub Actions workflow が遅くなったが、job total duration だけでは原因が分からない。
Composite actions を多用していて、その内部でどの処理が遅いか見たい。
最近 N 回の run で slow step を集計し、一回限りの外れ値と分けたい。
CI performance report を PR、issue、internal review に貼りたい。
たまに CI を診断するだけなので、metrics storage を維持したくない。
Config file で job filtering や matrix name normalization を行いたい。

長期 trend monitoring、cross-repository dashboard、cost report を作りたいなら、ghaperf だけで完結するとは限りません。むしろこれは診断 tool です。ある pipeline が遅いと感じたとき、log を分解して最初に見るべき場所を出す tool と考えるのが自然です。

注意したい境界

ghaperf は GitHub job log に依存します。そして GitHub の log format は正式な安定 protocol ではありません。README でも、parser は観測された format をもとにしており、GitHub が format を変えた場合は修正が必要になる可能性があると説明されています。

Log retention も制約です。GitHub Actions の log は default で 90 日保持されますが、organization 設定で変わります。古い run の log が削除済みなら ghaperf は分析できません。完了直後の job も、GitHub 側の log processing が終わるまで少し待つ必要がある場合があります。

また、ghaperf が示すのは「どこが時間を使っているか」です。「どう直すべきか」は自動では決まりません。rustup update が遅いと分かっても、cache を使うのか、toolchain を固定するのか、preinstalled runner を選ぶのか、あるいは受け入れるのかは project context 次第です。

まとめ

suzuki-shunsuke/ghaperf は狭くて実用的な CI 診断 CLI です。大きな observability platform を作るのではなく、GitHub Actions の API と job log から step、log group、job duration を取り出し、「CI が遅い」という曖昧な問題を議論できる report にします。

GitHub Actions をよく保守する team にとって、とくに価値があるのは composite action 内部が見えることです。時間の浪費はこうした wrapper step の中に隠れがちです。ghaperf はそれを開き、推測ではなく evidence に基づいて改善を始められるようにします。

リポジトリ：https://github.com/suzuki-shunsuke/ghaperf