gha-doctor

gha-doctorは、ゼロ構成でワンコマンドでGitHub Actionsワークフローのフラッキジョブ、無駄な分、遅いステップ、キャッシュ問題、ワークフローのアンチパターンを診断するコマンドラインツールである。READMEでは、正しさをカバーするactionlint、セキュリティをカバーするzizmorと並べ、速度・コスト・信頼性をカバーするものとして位置づけている。.github/workflowsから静的チェックを読み取り、既存のGITHUB_TOKENまたはgh CLI認証を使用して実行履歴分析を行う；lint専用モードは認証なしでオフラインでも動作する。--repo owner/nameフラグで別のリポジトリのワークフローファイルと実行履歴をAPI経由で取得できるため、リポジトリをクローンする必要がなく、--orgで組織全体やユーザーのフリート調査が可能。 静的解析は、D001からD021までの21の文書化されたルールで構成され、重大度と行番号が正確なYAML箇所を指し示す。これらは以下をカバーする：プルリクエストワークフローでのcancel-in-progressを含む並行性欠如、timeout-minutesのないジョブ、組み込みキャッシュ入力なしのsetup-node/setup-python/setup-java、フル履歴のcheckout、15分より頻繁なcron、すべてのpushでのmacOSおよびWindowsランナー、cache-fromなしのdocker build-push、restore-keysなしのactions/cache、ジョブレベルのcontinue-on-error、デフォルトのアーティファクト保持期間、大規模なマトリクス、npm ciではなくnpm install、スコープなしのpush plus pull_requestの重複トリガー、minute 0のcron、シャットダウンまたは退職したランナーラベルとアクションバージョン、自動化されたアクションピン更新の欠如、非推奨のワークフローコマンド、公開アクションでの非推奨Nodeランタイム、リポジトリガードなしのスケジュールワークフローなど。問題行へのコメントまたは--disableによるグローバル無効化で見込みを沈静化でき、各ルールは--explainでオフラインで説明可能。 実行履歴解析は、同じコミットで失敗と成功の両方の履歴を持つジョブを検出してフラッキジョブを特定し、ワークフロー別成功率、p50およびp95所要時間、キュー待ち時間とコストを報告し、最遅ステップと無駄な分を特定し、キャッシュヒット率とミス率を測定し、ジョブログからフラッキテストを名指しできる。測定結果すべてが0〜100の明細付きヘルススコアに集約され、SVGバッジとして出力可能。出力フォーマットにはプレーンテキスト、公開JSON Schemas付きの機械可読JSON、Markdown、SARIF 2.1.0、インライン注釈用ワークフローコマンド、インラインチャート付き自己完結型HTMLレポートが含まれる。 自動修正モードは修正可能なルールに対して精査な行編集を適用し、差分モードで変更を上書きせずにプレビュー可能。.gha-doctor.ymlまたは.github/gha-doctor.ymlのリポジトリ設定ファイルで、無効化ルール、履歴サンプルサイズ、ログサンプリング、失敗閾値などのポリシーを設定でき、明示的なCLIフラグが優先され、no-configフラグでこれを無視できる。終了コード2は警告を意味し、ツールでCIをゲート可能。重大度ゲートと最小ヘルススコア閾値を設定可能。 本プロジェクトは Composite GitHub Actionとしても提供され、リリースバイナリのインストールとargs、バージョン、トークン、ジョブサマリー、sticky PRコメント、ベースブランチとの差分比較、失敗閾値などの入力に対応し、インライン注釈はデフォルトで有効。GitHub Enterprise ServerはGH_HOST変数でサポートされる。Model Context Protocolのstdioサーバーモードはanalyze_repo、lint_repo、preview_fixes、run_deep_dive、org_overview、explain_ruleの6つの読み取り専用ツールを公開し、MCPクライアントがCIヘルスをクエリ可能。サーバーは公式MCPレジストリに登録され、コンテナイメージからも実行可能。 インストールオプションにはgh CLI拡張、Homebrew、Scoop、distrolessマルチアーキDockerイメージ、go install、aqua、mise/ubi、asdf、リリースバイナリ、deb/rpm/apkパッケージ、シェル補完、pre-commitフックが含まれる。ブラウザプレイグラウンドはWebAssembly経由でクライアントサイドでlintと自動修正を実行。READMEによると本プロジェクトはAIエージェントによってビルド・維持されており、ツールは常にリポジトリからの読み取りのみを行う。プライベートリポジトリ利用にはActions readおよびContents read権限が必要。