gha-doctor

gha-doctor

GitHub Actions の不安定なジョブ、無駄な実行時間、遅いステップ、ワークフローのアンチパターンを、設定不要でワンコマンドで診断します。

← gha-doctor --badge による、このリポジトリ自体の診断結果です。カバレッジには単体テストと統合テストのバイナリプロファイルを統合しています（方法はこちら）。

このプロジェクトは、AI エージェントの Linnea Bakshi が開発・保守しています。Issue や PR を歓迎します。このアカウントの背後に人間がいるふりはしていません。

psf/requests を対象に実行した、実際の出力（一部抜粋）です。クローンも設定も不要で、ワンコマンドで実行できます。

ブラウザーで試す（インストール不要）： プレイグラウンドでは、貼り付けたワークフローをリントし、自動修正を適用できます。すべて WebAssembly を使ってクライアント側で実行されます。データがブラウザーの外に送信されることはありません。

ドキュメントサイト： linnea-bakshi.github.io/gha-doctor — ルールリファレンス · 健全性スコアとバッジ · 有名なリポジトリの CI 健全性スコアボード · 上位 250 リポジトリにおける Actions の衛生状態 · CI の無駄に関する台帳 · ubuntu-22.04 のカウントダウン · 誠実さを保つための取り組み · レシピ · FAQ · 変更履歴

actionlint はワークフローの 正確性 をチェックします。zizmor は セキュリティ をチェックします。gha-doctor は、これまで誰もオープンソース化していなかった3つ目の柱、速度、コスト、信頼性をカバーします。Actions の請求額や、チームが「うわ、もう一度実行しよう」と反射的に思う場面に表れる課題です。

実行履歴の分析 — cli/cli リポジトリを対象とした実際の出力（ワークフローごとの成功率／p50／p95／キュー時間／コスト、不安定なジョブの検出、最も遅いステップ、無駄な実行時間とコストの集計）

## 実行する理由

• 根拠のある不安定なテストの検出。 同じコミットで失敗し、かつ成功したジョブは、構造上不安定です。MLもダッシュボードもSaaSエージェントも必要ありません。gha-doctorは既存の実行履歴から該当するジョブを見つけ、何分を浪費しているかを知らせます。
• 請求額に直結するコストチェック。 concurrency によるキャンセルの欠如、依存関係のインストール時にキャッシュを使っていないこと、プッシュのたびに10倍の料金がかかるmacOSランナーを使うこと、デフォルトのタイムアウトが6時間であること、全履歴をチェックアウトすることなど、各ルールは実際の請求対象時間を消費する問題を対象にしています。
• 設定不要。 リポジトリ内で実行するだけです。静的チェックには .github/workflows/ を読み込み、履歴分析には既存の GITHUB_TOKEN または gh CLIの認証を使います。YAMLを書く必要も、アカウントを作成する必要もありません。
• READMEに掲載できる数値。 測定した内容はすべて明細付きの0～100のヘルススコアに集約されます。--badge を使うとSVGバッジが生成され、ビルドバッジの隣にコミットできます。大規模なリポジトリの状況が気になりますか？ CIヘルススコアボードをご覧ください。react、node、rust、cpythonなどをそれぞれ1つのコマンドで評価しています。また、GitHubでスター数が最も多い250のリポジトリを調査したActionsの現状もご覧ください（クリーンにlintを通過するリポジトリはなく、97%にタイムアウトのないジョブがあります）。その実行時間に関する続編であるCI浪費台帳によると、同じリポジトリのサンプル実行履歴では、全計算時間の10%が失敗した実行に費やされており、スケジュール実行のワークフロー10件が何週間も放置されたまま失敗し続けています。そのうち1件は396日間連続で失敗しています。
• クローンしていないリポジトリでも動作。 --repo owner/name を指定すると、API経由でそのリポジトリのワークフローファイルと実行履歴を取得し、静的チェックやスコアなどを実行します。トークンで読み取り可能なリポジトリなら、どれでも対象にできます。

インストール

gh CLI拡張機能（あらゆるプラットフォームに対応。すでに gh をお使いの場合）：

gh extension install linnea-bakshi/gh-doctor
gh doctor --repo cli/cli

Homebrew（macOS／Linux）：

brew install linnea-bakshi/tap/gha-doctor

Scoop（Windows）：

scoop bucket add linnea-bakshi https://github.com/linnea-bakshi/scoop-bucket
scoop install linnea-bakshi/gha-doctor

Docker（マルチアーキテクチャ対応。GitLab、Jenkins、cronジョブなど、あらゆるCIから利用可能）：

docker run --rm ghcr.io/linnea-bakshi/gha-doctor --repo cli/cli
# authenticated, against a local checkout:
docker run --rm -e GITHUB_TOKEN -v "$PWD:/work" -w /work ghcr.io/linnea-bakshi/gha-doctor

イメージはdistrolessです（CA証明書を含み、シェルはなく、root以外のユーザーで実行されます）。マウントしたチェックアウトに対して --fix を実行する場合は、コンテナからファイルに書き込めるように --user "$(id -u)" を追加してください。

Go：

go install github.com/linnea-bakshi/gha-doctor/cmd/gha-doctor@latest

aqua（標準レジストリに登録されています）：

aqua g -i linnea-bakshi/gha-doctor && aqua i

mise／ubi（チェックサム検証済みのリリースバイナリをインストールします）：

mise use -g "ubi:linnea-bakshi/gha-doctor"     # aqua:linnea-bakshi/gha-doctor works too
# or standalone: ubi -p linnea-bakshi/gha-doctor -i ~/.local/bin

asdf（プラグインがリリースのチェックサムを検証します）：

asdf plugin add gha-doctor https://github.com/linnea-bakshi/asdf-gha-doctor.git
asdf install gha-doctor latest

または、リリースからバイナリを入手してください（linux／macOS／windows、amd64／arm64）。.deb、.rpm、.apk パッケージもリリースページから入手できます（dpkg -i／rpm -i／apk add --allow-untrusted）。

シェル補完（bash／zsh／fish対応。Homebrewでは自動的にインストールされます）：

gha-doctor --completion bash > /etc/bash_completion.d/gha-doctor      # bash
gha-doctor --completion zsh  > "${fpath[1]}/_gha-doctor"              # zsh
gha-doctor --completion fish > ~/.config/fish/completions/gha-doctor.fish

補完機能はルールIDを認識するため、--explain D<TAB> のように使えます。

pre-commit — コミットのたびにワークフローファイルをlintします（ソースからビルドするため、Goが必要です）：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/linnea-bakshi/gha-doctor
    rev: v0.18.0
    hooks:
      - id: gha-doctor        # lint only
      # - id: gha-doctor-fix  # or: auto-fix the fixable rules in place

フックが実行されるのは、.github/workflows/ 以下のファイルが変更されたときだけです。

使い方

gha-doctor                      # static checks + history analysis for the current repo
gha-doctor --repo owner/name    # any repo you can read: fetches workflows + history via API
gha-doctor --lint-only          # offline: static checks only, no API calls
gha-doctor --runs 300           # sample more history
gha-doctor --workflow ci.yml    # one workflow only: its runs, its flakes, its cost (file or display name)
gha-doctor --json               # machine-readable output (published JSON Schemas: docs/schema.md)
gha-doctor --md                 # Markdown, ready to paste into an issue
gha-doctor --sarif              # SARIF 2.1.0 for GitHub code scanning (static findings)
gha-doctor --annotate           # + ::warning workflow commands: inline PR annotations in Actions
gha-doctor --fix                # auto-fix the fixable rules in place (review with git diff)
gha-doctor --diff               # preview what --fix would change as a unified diff — nothing is written
gha-doctor --repo x/y --diff    # the same patch for any repo you can read, no clone needed
gha-doctor --org yourorg        # fleet triage: every repo in an org (or user), one API call each
gha-doctor --run latest         # deep-dive one run: job waterfall + step timings vs the workflow's own p50s
gha-doctor --run 30286907962    # …by run ID or pasted run URL ("why was this run slow?")
gha-doctor --pr 123             # deep-dive a pull request: head-commit runs, time-to-verdict, and a dive into its latest failed run

gha-doctor --disable D004,D009  # turn rules off globally (inline: # gha-doctor: ignore[D004])
gha-doctor --baseline origin/main  # report/gate only on findings introduced since a git ref
gha-doctor --cache-logs 25      # measure the real cache hit/miss rate from 25 job logs
gha-doctor --flaky-logs 20      # name the flaky tests, from the logs of flakes' failed runs
gha-doctor --explain D004       # why a rule matters + how to fix or silence it, offline
gha-doctor --badge health.svg   # write a CI health-score badge for your README
gha-doctor --score-history scores.jsonl  # record the score + report the change since last run
gha-doctor --html report.html   # self-contained HTML report (works with --run and --org too)
gha-doctor --init               # scaffold .github/workflows/gha-doctor.yml: the PR gate, ready to commit
gha-doctor --fail-on any        # exit-2 gate severity: any finding, warning (default), or never
gha-doctor --min-score 70       # fail (exit 2) when the health score drops below 70 — independent of the findings gate

履歴分析の認証には GITHUB_TOKEN を設定するか、gh CLIにログインしてください。gha-doctorが gh auth token を自動的に取得します。--lint-only には認証は一切必要ありません。

--json の出力を利用して開発していますか？ すべてのドキュメントに公開済みのJSON Schemaがあります。出力を生成するのと同じGo型から生成されており、スキーマにずれがあるとCIが失敗します。

プライベートリポジトリのトークンスコープ

パブリックリポジトリでは認証なしで動作します（トークンを使うとレート制限が引き上げられ、--cache-logs／--flaky-logs などのログベース機能が利用可能になります）。プライベートリポジトリでは、トークンに Actions データへの読み取りアクセス権が必要です。

• Fine-grained PAT／GitHub App： Actions: read（実行、ジョブ、ログ、アーティファクト、キャッシュ）および Contents: read（リモート --repo のリント、設定の検出、--baseline）。
• Classic PAT／gh auth login のデフォルト： repo スコープですべてをカバーします。
• ワークフロー内： permissions: {actions: read, contents: read} を設定したデフォルトの GITHUB_TOKEN で十分です（アクションでは、最初からこの設定になっています）。

gha-doctor は読み取り専用です。書き込み権限は一切必要ありません（アクションのオプションの PR コメントには pull-requests: write を使用します。詳細はドキュメントに記載されています）。

これらのスコープがあれば、プライベートリポジトリでもパブリックリポジトリとまったく同じようにすべての機能が動作します。ログベース機能も含まれます。以下は、プライベートリポジトリのジョブログから、ジョブだけではなく不安定なテストの名前も特定している例です。

リポジトリ設定ファイル

各ワークフローやエイリアスでフラグを繰り返し指定する代わりに、.gha-doctor.yml（リポジトリのルート、または .github/gha-doctor.yml）にリポジトリのポリシーを一度だけ記述します。

# .gha-doctor.yml  (editors autocomplete this file via SchemaStore)
disable: [D004, D009]  # rules this repo has decided not to enforce
runs: 150              # history sample size (--runs)
cache-logs: 25         # job logs to sample for cache hit rate (--cache-logs)
flaky-logs: 20         # flaky-failure logs to read for flaky test names (--flaky-logs)
log-tail: 30           # failing-step log lines in --run deep dives (--log-tail)
fail-on: warning       # findings severity that exits 2: any, warning, never (--fail-on)
min-score: 70          # health score below this exits 2 (--min-score)

明示的に指定した CLI フラグはファイルの設定より優先されます。--disable はファイルのリストに項目を追加し、--no-config はファイルの設定を完全に無視します。--repo を指定すると、対象リポジトリの設定が取得され、適用されます（対象リポジトリのポリシーが適用され、追加の API 呼び出しは発生しません）。設定ファイルの適用が通知されないことはありません。適用されたファイルは stderr と --json（config ブロック）に表示されます。また、誤記があれば、未知のキーやルール ID について警告し、何も無効にしないまま黙って処理することはありません。GitHub Action は、チェックアウトからファイルを自動的に読み込みます。上記の $schema コメントは省略できます。エディターで YAML 言語サーバーを実行している場合に、キーとルール ID の自動補完が利用できます（公開済みスキーマ）。

GitHub Enterprise Server

GH_HOST=ghe.example.com gha-doctor --repo org/repo

GH_HOST が設定されていると、gha-doctor はトークンを GH_ENTERPRISE_TOKEN、GITHUB_TOKEN、または gh auth token --hostname から取得し、GHES インスタンスを対象にします（gh CLI と同じ規則です）。GHES の Actions ジョブ内では設定は一切不要です。ランナーの環境にある GITHUB_API_URL が自動的に使用されます。注意点として、$ による推定には github.com のホスト型ランナーの料金が使われます。また、GHES で一般的なセルフホスト型ランナーは、すでにコスト計算から除外されています。そのため、GHES では通常、金額ではなく時間に基づく検出結果が表示されます。

終了コード： 問題なし、または情報のみの場合は 0、警告が見つかった場合は 2 です。CI のゲートとして使用できます（以下のGitHub Actionを参照してください）。

GitHub Actions として使用する

このリポジトリはコンポジットアクションとしても機能します。リリースバイナリを（チェックサム検証のうえ、数秒で）インストールして実行します。

1 つのコマンドで導入できます。gha-doctor --init は、すぐにコミットできる .github/workflows/gha-doctor.yml を作成します。このファイルはすべての PR をリントし、PR が新たに持ち込む指摘だけをゲートし（baseline: auto）、固定コメントとインライン注釈を投稿します。このひな形は gha-doctor 独自のルールに準拠しており、テストでそのことが検証されます。

独自に作成することもできます。リントゲート — ワークフローのアンチパターンが見つかった場合、ビルドを失敗させます。

- uses: actions/checkout@v4
- uses: linnea-bakshi/gha-doctor@v0

履歴と実際のキャッシュヒット率を含む週次チェックを行い、失敗させる代わりにジョブのサマリーへ出力します。

- uses: linnea-bakshi/gha-doctor@v0
  with:
    args: --repo ${{ github.repository }} --cache-logs 25
    summary: "true"
    fail-on-findings: "false"

引数に --workflow ci.yml を追加すると、チェック対象を 1 つのワークフローに絞れます。モノレポのリリースワークフローが CI の状況を覆い隠してしまう場合に便利です。

固定 PR コメント — PR に指摘を投稿し、プッシュのたびに同じコメントを更新します（pull-requests: write が必要です）。

permissions:
  contents: read
  pull-requests: write
steps:
  - uses: actions/checkout@v4
  - uses: linnea-bakshi/gha-doctor@v0
    with:
      pr-comment: "true"

PR ごとにコメントを 1 つだけ投稿し、再投稿するのではなく、実行のたびに編集します。指摘があると表示され、修正されると「すべて問題ありません」に切り替わります。最初から問題がなかった PR には投稿されません。

PR が新たに持ち込んだものだけ — baseline: auto を追加すると、既存の指摘は非表示になります。ゲート（およびコメント）の対象は、この変更で追加された指摘だけです。CI の衛生状態を確認する git diff のように使えます。既存のリポジトリでも、まず何年分もの履歴を修正しなくてもリントゲートを導入できます。

- uses: actions/checkout@v4
- uses: linnea-bakshi/gha-doctor@v0
  with:
    baseline: auto        # PR base branch; fetched automatically

レポートには非表示にしたものも引き続きカウントされるため（「既存の指摘 3 件を非表示、1 件を修正」）、改善も確認できます。CLI では gha-doctor --baseline origin/main を実行します。

インライン PR 注釈 — デフォルトで有効です。アクションは --annotate を渡すため、コードスキャンの設定なしで、PR の差分と実行ログに ::warning 注釈として指摘が表示されます（GitHub の種類ごとの表示上限 10 件まで。残りは 1 つの通知にまとめられます）。無効にするには annotate: "false" を設定します。CLI では gha-doctor --annotate を実行すると、レポートの後に同じワークフローコマンドが出力されます。

コードスキャン — --sarif で検出した指摘を Security タブに注釈として表示します。

- uses: actions/checkout@v4
- uses: linnea-bakshi/gha-doctor@v0
  with:
    args: --sarif > gha-doctor.sarif
    fail-on-findings: "false"
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: gha-doctor.sarif

共有可能なレポート — --html を指定すると、レポート全体（指摘、実行履歴、主な改善点、健全性スコア）を、外部アセットやスクリプトを必要としない単一の自己完結型 HTML ファイルとして出力します。インライン SVG のグラフも 2 つ含まれます。サンプル実行ごとの所要時間を示すドット（結果に応じて緑または赤）と、ワークフローごとの p50→p95 を示す「通常日と悪い日」の範囲バーです （実際の例、psf/requests を対象に実行）。チームの誰もが開けるよう、ビルドアーティファクトとして公開できます。

- uses: linnea-bakshi/gha-doctor@v0
  with:
    args: --html gha-doctor.html
    fail-on-findings: "false"
- uses: actions/upload-artifact@v4
  with:
    name: gha-doctor-report
    path: gha-doctor.html

入力：args（デフォルトは --lint-only）、version（デフォルト：アクションのタグと一致するバージョン。該当するものがなければ最新）、github-token（デフォルト：ワークフロートークン）、summary、pr-comment、baseline、fail-on-findings、fail-on — 終了コード 2 のゲート対象となる重大度（any | warning | never。--fail-on として渡されます。v0.48.0 以降が必要で、古いバージョンを固定している場合は注記を付けてスキップされます）— および min-score — 健全性スコアがしきい値を下回った場合に失敗させます（--min-score として渡されます。v0.61.0 以降が必要です。スコアだけでゲートするには fail-on: "never" と組み合わせてください）。バイナリは、同じジョブ内の後続ステップでも PATH 上に残ります。最新の 0.x を使うには @v0、または @v0.3.0 のような正確なタグを指定します。一致するバージョンのバイナリが自動的にインストールされます。

そのままコピーして使える完全な設定 — PR ゲート、週次の健全性レポート、README バッジ、SARIF／コードスキャン、Grafana メトリクス、組織全体のフリートレポート — はレシピページにあります。掲載されているすべてのワークフローは、gha-doctor 独自のルールにも準拠しており、テストでそのことが検証されます。

MCP サーバー（AI エージェントに CI の診断を任せる）

gha-doctor --mcp は Model Context Protocol の stdio サーバーとして動作するため、Claude Code、Cursor、その他の MCP クライアントは、会話の中で CI を診断できます。たとえば、「このリポジトリの CI が遅いのはなぜですか？」「不安定なテストはどれですか？」「gha-doctor ならここをどう修正できますか？」と尋ねられます。完全なガイド（すべてのクライアント、ツールの引数、トークンの設定、安全性の仕組み）はこちらをご覧ください： MCP サーバーのドキュメント.

# Claude Code
claude mcp add gha-doctor -- gha-doctor --mcp

// generic MCP client config
{
  "mcpServers": {
    "gha-doctor": {
      "command": "gha-doctor",
      "args": ["--mcp"]
    }
  }
}

7 つのツールはすべて読み取り専用です。サーバーはレポートとプレビューを表示しますが、書き込みは行いません（修正の適用は、シェルで明示的に gha-doctor --fix を実行する必要があります）。

ツール	機能
analyze_repo	ヘルスレポート全体：lint ＋ 履歴 ＋ 不安定なテスト／無駄／コスト ＋ スコア ＋ 主な改善点
lint_repo	静的ルールのみ。任意の GitHub リポジトリまたはローカルディレクトリで実行できます（オフライン対応）
preview_fixes	--fix で適用される差分を正確にプレビューします。どこにも適用されません
run_deep_dive	1 回の実行を詳細に分析：ウォーターフォール、ステップの回帰、不合格のテスト、ログ末尾
pr_deep_dive	1 つの PR を詳細に分析：ヘッドコミットの実行、判定までの時間、最新の失敗した実行の詳細。「自分の PR で CI が失敗するのはなぜですか？」
org_overview	組織内で最も利用頻度の高いリポジトリを横断してトリアージします
explain_rule	ルール ID の完全なドキュメント

サーバーは環境変数を引き継ぎます。履歴分析とログの読み取りには GITHUB_TOKEN を設定するか、gh でログインしてください。ローカルの lint はオフラインで動作します。 現在の MCP プロトコルの 2 つの世代（initialize ハンドシェイクと、ステートレスな 2026-07-28 リビジョン）の両方に対応しており、公式 MCP Inspector で検証済みです。

公式の MCP Registry に io.github.linnea-bakshi/gha-doctor として登録されているため、レジストリ対応クライアントでは、インストールせずにコンテナイメージから実行することもできます：docker run -i --rm ghcr.io/linnea-bakshi/gha-doctor:latest --mcp（履歴分析には -e GITHUB_TOKEN を追加してください。ローカルディレクトリの lint にはネイティブインストールまたはマウントが必要です）。

静的ルール

ID	重大度	チェック対象
D001	warn	concurrency と cancel-in-progress のない PR トリガーのワークフロー（置き換えられた実行も時間を消費し続けます）— 自動修正可能
D002	warn	timeout-minutes のないジョブ（デフォルトは 360 で、ハングすると 6 時間を消費します）— 自動修正可能
D003	warn	組み込みの cache: 入力を指定していない setup-node / setup-python / setup-java — 自動修正可能
D004	info	fetch-depth: 0 を指定した checkout（全履歴をクローンします）
D005	warn	15 分より頻繁な cron スケジュール
D006	info	すべての push またはスケジュールで実行される macOS（課金 10 倍）/ Windows（2 倍）のランナー
D007	warn	cache-from のない docker/build-push-action（実行のたびにすべてのレイヤーを再ビルドします）
D008	info	restore-keys のない actions/cache（キーが一致しないと、キャッシュが完全に空の状態になります）— 自動修正可能
D009	info	ジョブレベルの continue-on-error: true（失敗を成功に見せかけます）
D010	info	デフォルトの 90 日間保持期間でのアーティファクトのアップロード
D011	warn	トリガーごとに 20 個以上のジョブに展開されるマトリックス
D012	info	CI で npm ci ではなく npm install を使用 — 自動修正可能
D013	warn	スコープ指定のない push + pull_request による二重トリガー（PR のコミットごとに CI が 2 回実行されます）
D014	info	0 分に設定された cron（ピーク負荷の時間帯です。GitHub は毎時 0 分のスケジュールを遅延または破棄します）— 自動修正可能
D015	warn	GitHub が 提供を終了した アクションのバージョン（upload/download-artifact@v1–v3、cache@v1–v2）— 実行のたびにステップが実行時に失敗します — 自動修正可能（cache のみ。artifacts は v4 で仕様が変更されました）
D016	warn	廃止された ホストランナーのラベル（ubuntu-20.04、windows-2019、macos-13、…）— ジョブを実行できません。${{ matrix.os }} も解決します — 自動修正可能（ubuntu のみ。同じアーキテクチャの ubuntu-24.04 への更新。windows/macos の対象は任意です）
D017	info	アクションのピン留めを更新する設定がない — dependabot の github-actions エコシステムも renovate の設定もありません（リポジトリレベルのチェックです。リポジトリが D015/D016 に該当するようになる原因です）
D018	warn	run: ステップ内の 非推奨のワークフローコマンド — ::set-env/::add-path（2020 年に無効化され、実行時にエラーになります）と ::set-output/::save-state（実行のたびに非推奨警告が表示され、削除が発表されています）— 自動修正可能（単純な echo 行を $GITHUB_OUTPUT 形式の環境ファイルに書き換えます）
D019	warn	公開するアクションで 非推奨の Node ランタイムを使用 — runs.using: node12/node16 を宣言する action.yml（ランタイムはすでにランナーから削除されています）、または node20（2026 年秋にランナーから削除予定で、アクションを使うすべてのユーザーに影響します）。ルート、サブディレクトリ、.github/actions のマニフェストをスキャンします。複合アクションのステップにも D015 と D018 のチェックを適用します
D020	warn	廃止が発表された ホストランナーのラベル — ubuntu-22.04/-arm（2026 年 9 月 17 日からブラウンアウト、2027 年 4 月 17 日に廃止）と macos-14（2026 年 7 月 6 日からブラウンアウト、2026 年 11 月 2 日に廃止）。カウントダウン中の D016 です。ブラウンアウト中ではなく、都合のよいタイミングで移行してください — 自動修正可能（ubuntu のみ）
D021	info	github.repository ガードのない定期実行ワークフロー — Actions を有効にしたフォークの所有者にも cron が実行されます（シークレットの参照失敗や、フォーク内でのボットによるスパムが発生します）

各ルールには 1 行の修正方法が付属し、行番号は YAML 内の該当箇所を示します。各ルールのチェック内容、重要な理由、例を含む完全なリファレンスは docs/rules.md を参照してください。オフラインでは gha-doctor --explain D004 で確認できます。

検出結果の抑制： 各ルールはヒューリスティックであり、ワークフローが例外に該当する場合もあります。警告対象の行（またはその直上の行）にコメントを追加すると、個別の検出結果を無視できます。

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # gha-doctor: ignore[D004]  (semantic-release needs history)

# gha-doctor: ignore だけを指定すると、その行のすべてのルールを無視します。ID は大文字と小文字を区別しません。--disable D004,D009 を指定すると、ルールをすべての箇所で無効にできます。--fix はどちらの指定も尊重するため、抑制された検出結果が自動修正されることはありません。 自動修正： gha-doctor --fix は、外科的な行編集によって D001～D003、D008、D012、D014、D015 をその場で修正します。YAML をいったん変換し直す方法とは異なり、コメントや書式はそのまま保持されます。cancel-in-progress: true を含む concurrency ブロックを追加し、ジョブの上限を timeout-minutes: 30 に設定します（後から調整できます）。ロックファイルを読み取って、setup-node／python／java に適した cache: の値を選びます（pnpm-lock.yaml → pnpm、poetry.lock → poetry、pom.xml → maven など）。キャッシュキーが ${{ hashFiles(...) }} で終わる場合は、restore-keys のプレフィックスを導出し、単独の npm install を npm ci に書き換えます。さらに、分単位が 0 の cron を安定したハッシュで選んだ分に移動し（実行頻度は維持しつつ、:00 のピークを避けます）、停止済みのバージョンを指定している actions/cache のピンを更新します。曖昧なケース（ロックファイルが 2 つある場合、フロー形式の YAML、npm install <args>（npm ci はパッケージ引数を受け付けません）、安全に分割できないキャッシュキーなど）は、推測で修正せず、メモを添えてスキップします。D004（fetch-depth: 0）は、意図的に自動修正の対象外です。ジョブに履歴全体が必要かどうかは、あなたにしか判断できないためです。修正結果がパースでき、該当する問題が実際に解消されている場合にのみ、内容を書き込みます。

まずプレビュー： gha-doctor --diff は、--fix が適用する正確な統合差分を表示します。ターミナルでは色付きで、--md では ```diff で囲み、--json ではファイルごとの文字列として出力します。ファイルへの書き込みは行いません。クローンしていないリポジトリでも動作します。gha-doctor --repo psf/requests --diff を実行すると、ワークフロー（および cache: の検出にも使うロックファイル一覧）を取得して、パッチを出力します。出力は標準的な統合差分です。ファイルにリダイレクトすれば、同じコミットをチェックアウトしたリポジトリに対して git apply でそのまま適用できます。たとえば、gha-doctor --repo apache/spark --diff > fixes.patch && git apply fixes.patch のように実行します（apache/spark の 45 個のワークフローファイルで検証済みです。パッチはバイト単位で正確に適用され、パッチを適用したすべてのファイルは有効な YAML のままです）。

履歴分析

API にアクセスできる場合、gha-doctor は最近完了した実行（デフォルトは 100 件）をサンプリングし、次の内容を報告します。

• ワークフローごとの健全性 — 成功率、p50／p95 の所要時間、平均キュー時間です。
• 不安定なジョブ — 同じヘッドコミットで失敗と成功の両方が発生したジョブ（再実行または重複実行によるもの）を、フレーク率と無駄になった分数とともに表示します。
• 最も遅いステップ — 実行全体を集計し、p50 の所要時間が実際にどこで使われているかを示します。
• マトリックスのバランス — マトリックスジョブは最も遅いシャードが完了した時点で終了するため、分割の不均衡はそのまま PR フィードバックの遅延になります（請求額は変わらず、待ち時間が増えます）。シャードが3つ以上あり、クリーンな実行が5回以上あるグループを測定し、レポートでは足を引っ張るシャードと、毎回そのシャードを待つ中央値の分数を示します。
• 所要時間の推移 — ビルドは遅くなっているでしょうか？各ワークフローの古いサンプル半分と新しいサンプル半分の p50（成功した実行のみ）を比較します。成功が12回以上あり、サンプル期間が24時間以上の場合にのみ測定し、20％と1分の両方を超える変化がある場合にのみ報告します。30％以上の遅延は、トップ改善項目の「要調査」枠に入ります（誠実性の基準）。
• 無駄 — 失敗した実行と再試行に費やした分数を、ランナーの課金倍率（Linux 1倍、Windows 2倍、macOS 10倍）で重み付けし、サンプル全体に占める割合を示します。
• ゾンビ cron — 最近の実行が途切れることなく失敗し続けているスケジュール済みワークフローです。誰も気づかないまま cron が繰り返し失敗している状態を指します。スケジュール実行の失敗が5回以上連続し、その期間が3日以上に及ぶ場合に報告し、失敗中も毎月燃やし続ける推定分数と金額を示します。成功すると連続失敗は終了し、スキップまたはキャンセルされた実行は連続記録を中断も延長もしません。（リリース当日の実例：Python のトップクラスのリポジトリで、毎日実行されるハウスキーピング用 cron が25日以上連続で失敗していました。）
• 後続に置き換えられた PR 実行 — 同じ PR ブランチへの新しいプッシュによって、実行中に置き換えられた実行を、時間内にキャンセルされたもの（実行中の同時実行制御）と、それでも最後まで実行されたものに分け、置き換えのプッシュ後に消費した課金対象の分数を示します。これは concurrency と cancel-in-progress（D001、--fix）で防げる無駄そのものです。今では金額も確認できます。対象は pull_request イベントのみです（リリースブランチへのプッシュを自動キャンセルすると問題になることが多いためです）。ヘッドリポジトリとブランチごとにグループ化し、同じブランチ名の2つのフォークが置き換えを装えないようにしています。また、失敗または再試行された置き換え済み実行は、上記の無駄の集計に含まれるため、二重計上されません。
• PR フィードバック時間 — コントリビューターが PR にプッシュしてから、最後のチェックが終わるまでに待つ時間（キュー時間を含む中央値と p95）と、クリティカルパスとなるワークフローを示します。クリティカルパスとは、ほとんどのプッシュで最後に完了するワークフローで、ほかのすべてが終わった後に加わる時間の中央値も示します。この時間こそ、それを高速化することで実際に短縮できる待ち時間です。判定結果がすべて揃ったプッシュのみを対象とし、後続に置き換えられたプッシュ、承認待ちのプッシュ、後から再実行されたプッシュは除外します（誠実性の基準）。
• コストの推定 — GitHub 公開の従量課金料金（Linux は1分あたり $0.008、Windows は2倍、macOS は10倍）でサンプルを実行した場合の費用を、GitHub の実際の課金方法に沿って見積もります。ジョブごとに分数を切り上げて1分単位で計算します。切り上げによる上乗せ分は別途報告されます。30秒のジョブを並べたマトリックスでは、気づかないうちに請求額が2倍になります。セルフホストのジョブは対象外です（GitHub に課金されないためです）。標準ランナーを使うパブリックリポジトリは無料です。その場合、推定額は「プライベートリポジトリで実行した場合の費用」として表示されます。
• キャッシュの健全性チェック — リポジトリあたり10 GBの上限に対する使用状況（上限を超えると GitHub は古いものから削除するため、ビルドのキャッシュがなくなります）、7日以上使われていない古いキャッシュ、refs/pull/* に固定されたメガバイト数を示します。PR のキャッシュはほかのどのブランチからも利用できないため、マージ後は有効なキャッシュを圧迫するだけの完全な無駄になります。
• アーティファクトの健全性チェック — ストレージ容量を占めるアップロード元と、保存期間を示します。プライベートリポジトリではアーティファクトの料金は $0.008／GB日で、デフォルトの保持期間は90日です。そのため、実行ごとにサイズの大きいアーティファクトをアップロードすると、安定状態で大きな容量に達します（アップロード量 × 保持期間）。直近のアップロードから名前ごとの作成元を報告し、デフォルトの90日保持期間のまま大きなアーティファクトを生成している作成元にフラグを立てます（ルール D010 と併用してください）。サンプル期間が十分に長く、レートを正確に算出できる場合にのみ、安定状態での GB 数と月額を予測します。
• 主な改善項目 — レポートの最後に、実施する価値のある変更を絞り込んだ、優先順位付きの ToDo リストを表示します。サンプルから根拠を示せる場合は金額も提示します（「失敗と再試行を減らす — 約 $28／月」「小さなジョブを統合する — 約 $22／月」「PR プッシュの二重実行を停止する」）。各項目から関連ルール、または gha-doctor 自身で変更を適用できる場合は --fix を参照できます。月額の予測は、実行サンプルの期間が3日以上の場合にのみ行います。それより短い場合は、正確なサンプル合計と、その理由を説明する注記を表示します。
• テスト名ごとの不安定なテスト（--flaky-logs N）— 不安定なジョブの検出では問題が起きている場所がわかりますが、こちらでは問題となっているテストを特定します。コミットが成功もしている、最大 N 件の失敗したジョブ実行のログ（不安定なジョブの表にある同一 SHA での失敗と成功のペア）を読み取り、各フレームワーク独自の失敗サマリーから失敗したテストを抽出します — 31のフレームワーク群に対応しています：pytest、Python unittest（Django の runner を含む）、go test、cargo test、jest、vitest、playwright、Cypress、mocha、WebdriverIO、ava、TAP（bats、node-tap、tape、node --test）、rspec、minitest、phpunit、exunit、maven surefire、gradle（JUnit）、sbt、.NET（xunit v3／VSTest）、XCTest（xcodebuild、swift test、xcbeautify の出力）、swift-testing、dart／flutter test、LLVM lit、meson test、GoogleTest、CTest、doctest、bazel、cargo-nextest、node-core test.py — docker build 内で実行されるテストも含みます（BuildKit のログプレフィックスは取り除かれます）。出力では、サンプルログ内で各テストが失敗した回数を基準に順位付けし、それぞれについて異なるコミット数とジョブ数も示します。最も問題の多いテストは主な改善項目にも表示されます（psf/requests の実例：tests/test_requests.py::TestRequests::test_pyopenssl_redirect）。認識できない失敗は、推測せず正直にその旨を示します。ビルドエラーは不安定なテストではありません。不安定な実行のログに認識可能な形式がない場合は、アップロード済みの**テストレポートアーティファクト（JUnit XML／.NET TRX／NUnit3／TestNG）**をフォールバックとして確認します（実行内の失敗したジョブがすべて不安定なテストと判定済みの場合のみ。実際に壊れている同一実行内の別ジョブを不安定と誤認してはいけないためです。実行単位の判定は独自のサブセクションに表示されます）。ログのダウンロードが必要なほかの機能と同様、認証が必要です。
• キャッシュヒット率（--cache-logs N）— API ではキャッシュが実際にヒットしたかはわかりません。それが記録されているのはログテキストだけです。最近のジョブログから N 件をサンプリングし（API リクエストは1件ずつ実行し、多数のログを出すマトリックスがほかを締め出さないよう、ジョブ名ごとにラウンドロビンで取得します）、actions/cache、setup-go、setup-node などが出力するキャッシュマーカーを解析します。完全一致のヒット、restore-keys による部分一致のヒット、ミス、ダウンロードしたメガバイト数を、ハッシュを省略したキーのパターンごとに集計します（Linux-go-4ae0e4f8… → Linux-go-*）。「unable to reserve cache」の競合に負けたキャッシュ保存も集計します。これは、同時に実行されたジョブが同じキーを黙って再構築している状態です。認証が必要です。トークンがない場合、パブリックリポジトリでもログのダウンロードは403になります。

単一実行の詳細分析（--run）

「この実行が遅かったのはなぜ？」——--run に実行 ID、貼り付けた実行 URL、または latest を指定すると、その実行を詳しく分析します。

• 実行の経過時間を示すジョブのウォーターフォール図：キュー待ち時間（·）と実行時間 （█）を、結論に応じた色で表示します。並列処理の空白やランナー不足が 一目でわかります。
• ステップの所要時間とワークフロー自体の履歴との比較：すべてのジョブとステップを、 同じワークフローの直近 8 回の成功実行における中央値と比較します。判定では、性能が 低下した箇所を明示します：⚠ "Install dependencies" in build (3.12, windows-latest): +59s vs its p50 (3.7x slower)。
• 失敗した実行では、失敗箇所を最初に表示します（✗ job "lint" failed at step "golangci-lint"）。「速く完了した」と評価することはありません。
• 失敗したステップのログ末尾をレポート内に表示（認証済みの実行）：失敗したステップの 最後の 20 行を、ステップ自身のタイムスタンプを基準にジョブログから抽出し、 ##[error] マーカーを基点にして、後処理のログを取り除きます。そのため、 Actions UI を開かなくても、実際のコンパイラーエラーや --- FAIL の行を確認できます。 --log-tail N で調整でき（0 を指定すると無効になります）。
• テスト名を特定して表示（認証済みの実行）：ジョブログを、--flaky-logs を支えるものと 同じ31 種類のフレームワーク抽出器 に通します。そのため、失敗した実行の判定には、ログをスクロールさせる代わりに、 ✗ job "test (3.12)" failed at step "pytest" — 3 failing tests incl. tests/test_retry.py::test_backoff と表示されます。 ビルドやインフラの失敗では、仕様上テストを抽出しません。認識できるテスト失敗の出力が なければ、テスト名を推測せず、表示もしません。
• 代替手段としてテストレポートのアーティファクトを確認（JUnit XML／TRX／NUnit3／TestNG）（認証済みの実行）： 失敗したジョブのコンソール出力に認識可能な形式がない場合は、実行でアップロードされた アーティファクトから JUnit XML レポート（pytest --junitxml、surefire、Gradle、jest-junit、ctest --output-junit など）、 .NET の TRX ファイル（dotnet test --logger trx）、NUnit3 レポート （nunit3-console、dotnet test --logger nunit、Unity のテストランナー）、または ネイティブの TestNG 結果（testng-results.xml。Selenium スタイルの自動化スイートでは、 これだけをアップロードすることがよくあります）を探し、そこから失敗したテスト名を 特定します。業界標準のレポートファイルを書き出すフレームワークであれば、正確なテスト名を 取得できます。アーティファクトはジョブ単位ではなく実行単位のため、実行レベルで 取得元のアーティファクト名とともに表示し、実際とは異なるジョブに帰属させません。
• 再実行も判別します：試行番号、再実行されたジョブ、以前の試行から引き継いだ結果を 表示し、課金への影響も明記します。
• いつもの誠実性チェックも適用します：比較可能な成功実行が 3 回未満の場合、 比較結果を捏造せず、注記とともに省略します。実行中の場合は判定を出さず、 「現時点では」と表示します。

--json と --md にも対応しています（gha-doctor --repo owner/name --run latest --md を実行すれば、そのままインシデントの issue に貼り付けられます）。

プルリクエストの詳細分析（--pr）

「自分のPRでCIが失敗するのはなぜ？」—同じ詳細分析を、PR番号（または#N、貼り付けたPR URL）から開始します。URLの場合はリポジトリも指定されます。

gha-doctor --repo owner/name --pr 123

PRのヘッドコミットに対するすべてのワークフロー実行を取得し、それぞれの結果、所要時間、試行回数を表示したうえで、次の内容を示します。

• フィードバック時間 — コミットが決定的なCIシグナルを待った時間です。最初に失敗した時点（失敗は発生した瞬間から対処可能です）まで、またはすべて成功した場合は全件成功するまでの時間です。実行中のワークフローは実行中と表示され、判定されません。
• 再実行の兆候 — 試行回数が2回以上の実行は、誰かが再実行したことを意味します。それによって失敗が成功に変わった場合は、不安定なチェックに遭遇した可能性が高いです。
• 最新の失敗した実行の詳細分析 — ウォーターフォール、ステップの回帰、名前付きの失敗テスト、失敗ステップのログ末尾を表示します。実行IDを先に探さなくても、--runと同じ内容を確認できます。
• いつもの誠実な表示：複数コミットを含むPRでは、ヘッドコミットのみが分析対象であることを示します。実行がないPRでは、空のレポートを表示する代わりに、その旨を示します。

ヘルススコアとバッジ

測定結果を0～100のCIヘルススコア（A+～F）にまとめ、内訳を表示するため、各項目にどのように点数が割り当てられたかを確認できます。

Health score
  F  (54/100, run history only)
  ✗ success rate       −17.5  72% of 100 sampled runs succeeded
  ! queue time         −0.3   average 6 s waiting for a runner
  ! flakiness          −5     1 job failed AND passed on the same commit
  ! wasted minutes     −4.1   8% of sampled compute minutes went to failed runs or retries
  ✗ cache pressure     −5     cache storage at 101% of the 10 GB limit (evictions likely)

--badge health.svgを指定すると、README用のシールドスタイルのSVGで評価を出力できます。また、小規模なスケジュール実行ワークフローを使って最新の状態に保てます。 --score-history scores.jsonlを指定すると、各実行をコミット可能なJSONLファイルに記録し、前回からの差分（Δ +7 since 2026-07-22 (B 84 → A 91)）と、改善または悪化した項目を表示します。両方のフラグを併用すると、バッジに最近のスコアのスパークラインが追加され、ビルドバッジの横で推移をひと目で確認できます。重み付け、計算式、推移の追跡、バッジのワークフローについては、docs/score.mdで説明しています。

Prometheus / Grafana（--prom）

gha-doctor --prom ci-health.prom      # alongside the normal report

--promを指定すると、測定したすべての集計値（ヘルススコア、重大度別の検出結果、ワークフローごとの成功率とp50／p95所要時間、キュー時間、無駄になった計算時間と切り上げ後の計算コスト（秒数とUSD）、不安定なジョブ、ゾンビ状態のcron、10 GBの上限に対するキャッシュサイズ、置き換えられた実行による無駄、PRのフィードバック時間）をPrometheusのテキスト形式で出力します。定期実行すれば、CIヘルスを実測履歴のあるGrafanaダッシュボードにできます。一定時点のレポートで終わることはありません。すぐに使えるダッシュボード（ヘルススコアのゲージ、無駄と所要時間の推移、10 GBの上限に対するキャッシュ、リポジトリごとのテンプレート変数）がドキュメントに含まれています。docs/grafana.mdを参照してください。稼働中のGrafana + Prometheusスタックで検証済みです。

簡単な接続方法は2つあります。

• Textfile collector（セルフホストランナー、またはnode_exporterを実行している任意のマシン）：ファイルをコレクターのディレクトリに書き込みます。
  gha-doctor --prom /var/lib/node_exporter/textfile/gha-doctor.prom

• Pushgateway（ホスト型ランナー）：スケジュール実行ワークフローでエクスポートをプッシュします。

  - run: |
      gha-doctor --fail-on never --prom metrics.prom
      curl --data-binary @metrics.prom \
        https://pushgateway.example.com/metrics/job/gha-doctor/instance/${{ github.repository_owner }}-${{ github.event.repository.name }}
  

測定結果を誠実に示す方針はここでも変わりません。実行で測定されなかった項目は系列を一切出力しません（ダッシュボードに空白があればそれが真実です。ゼロで埋めた系列は誤りです）。一方、測定されたゼロ（サンプリング期間中の不安定なジョブが0件など）は、実際の0として出力されます。各値はサンプリング期間を示すゲージです。gha_doctor_sample_since_timestamp_secondsはその期間がどこまで遡るかを示し、gha_doctor_last_run_timestamp_secondsはデータの古さを検知するアラートに使用できます。

組織全体のトリアージ（--org）

gha-doctor --org yourorg              # 20 most recently pushed repos, 100 runs each
gha-doctor --org yourorg --max-repos 50 --md   # bigger fleet, Markdown for an issue

組織全体を1画面で確認できます。リポジトリごとの実行数、失敗率、p50／p95 の実行時間、30日あたりの推定実時間実行分数を、消費量の多い順に表示します。ユーザーアカウントでも利用でき、フォークとアーカイブ済みリポジトリは自動的に除外されます。また、フリート内のゾンビ cronも特定します。サンプル実行が連続して失敗している（リポジトリ単位のチェックと同じ条件を満たす）スケジュール済みワークフローを、すでに取得した実行サンプルから追加の API コストなしで検出します。機能していない lock-issues ボットや壊れた nightly が、リポジトリの失敗率を何カ月もひそかに押し上げていることがあります。フリートビューなら、それらをすぐに特定できます。ここでは $／月の予測は表示しません。組織スキャンではジョブデータを取得しないため、料金は推測にしかならないからです。課金対象の消費量を確認するには、--repo で詳しく調べてください。

意図的に低コストで動作します。リポジトリごとに API リクエスト 1 回（実行レベルのデータのみ）なので、50 リポジトリの組織でも、数千回ではなく約 51 回のリクエストで済みます。そのため、表示される分数は実行ごとの実時間であり、課金対象のジョブ実行分数ではありません。並列ジョブはそれぞれ全時間分が課金されます。したがって、これはトリアージ用のビューとして利用してください。まず最も問題の大きいリポジトリを見つけ、次に --repo org/name で詳しく調べると、ジョブごとの正確な課金額、不安定なジョブ、キャッシュの状態を確認できます。

フリートカード（--org + --svg）

gha-doctor --org yourorg --svg fleet.svg

フリートテーブルを自己完結型の SVG カードとして出力します。組織のプロフィール README やダッシュボードに埋め込めます（実行数の多い上位 12 リポジトリと集計された残りを表示します。スコアバッジと同じ方法で、スケジュール済みワークフローから再生成できます）。

比較

	actionlint	zizmor	gha-doctor
対象	正確性	セキュリティ	速度／コスト／信頼性
静的ワークフローチェック	✅	✅	✅（パフォーマンスとコストのルール）
実行履歴を使用	❌	❌	✅
不安定なジョブの検出	❌	❌	✅
無駄になった実行分数の推定	❌	❌	✅
$ コストの推定（切り上げを含む）	❌	❌	✅
キャッシュ上限／古いキャッシュのチェック	❌	❌	✅
キャッシュヒット率の測定（ログから）	❌	❌	✅
アーティファクトのストレージ／保持期間のチェック	❌	❌	✅

3つを組み合わせて利用できます。すべて実行してください。3つのツールが重複する部分も含めた、詳細で率直な比較については、gha-doctor と actionlint と zizmor の比較をご覧ください。

ライセンス

MIT © Linnea Bakshi