Buildkite

公式

Buildkiteのパイプラインとビルドを管理します。

GitHub
56

Buildkite MCPで何ができますか？

  • 最近のビルドを確認する — アシスタントに、パイプラインの最近のビルドを一覧表示し、特定のビルドの詳細を list_builds と get_build を使って表示するよう依頼します。
  • 失敗したジョブを調査する — list_jobs、search_logs、tail_logs を使ってジョブ一覧を取得し、ログを読み取ったり検索したり、出力を追跡したりして、ビルドが失敗した原因を特定します。
  • 失敗したジョブを安全に再試行する — ドライランで再試行案を確認してから、インフラストラクチャの障害に限って retry_failed_jobs で再試行するか、retry_job で単一のジョブを再試行します。
  • 実行中のビルドを待つ — wait_for_build を使って、結果を報告する前にビルドが完了するまで待つようアシスタントに依頼します。
  • ビルドを比較する — 「このビルドが main で最後に成功してから、何が変わりましたか？」と尋ねると、新たに失敗したステップと復旧したステップをジョブ単位で比較できます。

ドキュメント

buildkite-mcp-server

Build status

Model Context Protocol (MCP) サーバー。Buildkite のデータ（パイプライン、ビルド、ジョブ、テスト）を AI ツールやエディターに公開します。

ドキュメント全文は buildkite.com/docs/apis/mcp-server をご覧ください。

限定的な権限でビルドを再試行する

retries ツールセットを使うと、より広範なビルド書き込み権限なしで、失敗の調査やジョブの再試行ができます。list_builds、get_build、 wait_for_build、list_jobs、get_job、search_logs、tail_logs、read_logs、 retry_job、retry_failed_jobs が含まれます。必要なスコープは read_builds、read_build_logs、retry_builds であり、write_builds は必要ありません。

buildkite-mcp-server stdio --enabled-toolsets retries

retry_failed_jobs はインフラストラクチャの失敗のみを再試行します。実行せずに再試行案を確認するには、dry_run オプションを使用してください。retry_job は特定のジョブを再試行します。どちらも変更を伴うツールであり、 --read-only では除外されます。このツールセットでは、作成、再ビルド、キャンセル、ブロック解除の操作はできません。既存の再試行ツールは builds で引き続き利用できます。builds または all を選択する場合、その他の変更操作には引き続き write_builds が必要です。

Buildkite API で RetryBuildsScope 機能が有効になっている場合、トークン所有者は retry_builds を使用できます。既存の write_builds トークンも引き続き受け付けられます。 ホスト型 MCP OAuth では、ホスト型サーバーがこの機能を含むリリースに更新された後、/mcp/x/retries を使ってこのツールセットを選択できます。リクエストヘッダーでツールセットを選択しても、既存のトークンの OAuth スコープは変更されません。

ライブラリ利用者の場合、WithDisabledToolsets と HTTP ファクトリーの無効化されたツールセットは、重複するグループを通じて利用できる場合も含め、それらのツールセットのすべてのメンバーを除外します。たとえば、logs を無効にすると、retries のログツールも削除されます。retries を無効にすると、その調査ツールと再試行ツールが他のグループからも削除されます。

GitHub Actions パイプラインの設定

create_pipeline と update_pipeline は、GitHub の provider_settings および branch_configuration を受け付けます。作成時に API のデフォルト値を使う場合、または更新時に値を変更しない場合は、プロバイダーのキーを省略してください。明示的な false は保持されます。 filter_condition または pull_request_branch_filter_configuration を null に設定すると、それらをクリアできます。空文字列は空文字列として送信されます。既存のブランチフィルターをクリアするには、更新時に branch_configuration: null を設定してください。 作成時にブランチフィルターを省略、null、または空にすると、API の null デフォルト値が使われます。完全な get_pipeline および list_pipelines レスポンスでは、サポートされている GitHub 設定が保持されます。go-buildkite のレスポンス文字列では null と空文字列を区別できないため、読み戻した値から部分更新を再構成しないでください。

GitHub Actions の手動セットアップ に従ってください。兄弟ワークフロービルドのスキップやキャンセルを避けるため、ブランチ全体に適用される skip_queued_branch_builds と cancel_running_branch_builds は false のままにしてください。create_webhook: false を使用してください。プロバイダー設定では専用の GitHub Actions トリガーやその Webhook はプロビジョニングされず、既存の Webhook ツールが作成するのは従来型のリポジトリ Webhook です。サーバー側での機能提供状況とトークンの権限は引き続き適用されます。設定が受け付けられても、ワークフローの実行が保証されるわけではありません。

作成時には、空白以外の configuration または 承認済みの pipeline_template_uuid を指定してください。両方は指定できません。更新時に割り当てを維持するには pipeline_template_uuid を省略します。configuration なしでテンプレートを割り当てるには UUID を指定し、テンプレートを削除するには null を送信します。削除時には、置き換え用の configuration を含めることもできます。設定要件と組織のテンプレートポリシーは API によって適用されます。完全なパイプラインレスポンスには割り当てられた UUID が保持されます。レスポンスの割り当てが null または存在しない場合、go-buildkite はこのフィールドを省略します。

従来型の GitHub Webhook 処理を調査または変更するには、get_pipeline_github_webhook_processing、 enable_pipeline_github_webhook_processing、disable_pipeline_github_webhook_processing を使用してください。これらは POST の webhook 作成エンドポイントではなく、GET/PUT/DELETE の github-webhooks を使用します。リポジトリ Webhook の削除や、専用の GitHub Actions トリガーの変更は行いません。レスポンスには enabled と、null 許容の disabled_at および disabled_by のメタデータが保持されます。disabled_by はユーザー名です。 3 つのツールすべてで、Full Access、GitHub または GitHub Enterprise のパイプライン、および拡張 Webhook トリガーへの組織の登録が必要です。GET には read_pipelines が必要です。有効化と無効化には write_pipelines が必要で、読み取り専用モードでは除外されます。404 は、パイプラインが存在しないのではなく、これらの操作が利用できないことを示す場合があります。API エラーは、失敗を無効状態として扱わず、そのまま返されます。

これらの仕様は、ローカルの合成 HTTP フィクスチャを使って検証されています。ホスト環境での提供状況、権限、永続化、ワークフロー実行については、別途確認が必要です。ローカルで成功しても、デプロイ環境でのサポートを証明するものではありません。専用の GitHub Actions トリガー管理は含まれていません。

ビルドの比較

investigations ツールセットに含まれる読み取り専用の compare_builds ツールは、「このビルドが main で最後に成功してから何が変わったか？」といった質問に答えます。org_slug、pipeline_slug、および対象の build_number を指定してください。同じパイプラインと完全一致するブランチで、対象より前に作成され、現在 passed になっているビルドのうち、最も新しいものを選択します。ベースラインが対象の開始時点ですでに passed だったことは要件ではありません。代わりに同じパイプライン内の特定のビルドと比較するには baseline_build_number を指定してください。失敗したビルドや別のブランチのビルドも指定できます。

レスポンスにはベースラインと選択ルールが示され、すべてのジョブの結果が集計されます。また、新たに失敗したステップ、復旧したステップ、引き続き失敗しているステップを優先して、最大 100 件のジョブ比較が返されます。照合にはステップキー、ジョブタイプ、マトリックス値、並列インデックスと合計数を使用します。両方のジョブにキーがない場合は、完全一致する空白以外の名前、タイプ、グループキー、マトリックス値、並列インデックスと合計数の組み合わせが各ビルドで一意である場合に限り、フォールバック照合を行います。照合されたペアには match_method: "step_key" または "name_fallback" が示されます。フォールバック照合には、ヒューリスティックであることを示す警告が付きます。名前のないキーなしジョブと、識別情報が重複するジョブは照合されません。明示的なキーがある場合、ビルド間でキーが追加、削除、変更されていても、名前によるフォールバックは行われません。追加／削除とは、ジョブの識別情報が一方のビルドにしか存在しないことを意味します。そのため、キーのないジョブの名前変更や、マトリックス値または並列数の変更によっても、追加／削除として表示されることがあります。再試行された試行は除外されます。最終試行の状態と再試行回数は引き続き表示されます。

実行時間と差分は最終試行のみを対象とします。スケジュール時間は scheduled_at から started_at までであり、依存関係による待機時間や手動待機時間ではありません。これらはビルド全体の経過時間の比較でも、再試行を含む総コストでもありません。タイムスタンプが欠落または不整合の場合、該当する時間は省略されます。未完了のビルドは、変化し続けるスナップショットとして明示されます。

soft_failed に変化がある場合は、すべて state_changed として報告されます。これには、両方のジョブの状態が failed であっても、ソフト失敗とハード失敗の間で遷移した場合や、passed とソフト失敗の間で遷移した場合が含まれます。ソフト失敗はビルドをブロックしないため、後者が newly_failing または recovered として報告されることはありません。passed のベースラインビルドにソフト失敗のジョブが含まれる場合もあります。

デフォルトでは、新たにブロック要因となった失敗のうち最大 3 件について、最後のログエントリ 20 件が含まれます。newly_failing のジョブが優先され、次に、ベースラインではソフト失敗だったジョブなど、現在ハード失敗となっている state_changed のジョブが続きます。各ログの内容は 8 KiB に制限されます。ログを省略するには include_logs: false を設定してください。HTTP 401 認証エラーはサーバーの再認証経路に伝播しますが、それ以外のログエラーによって比較結果が破棄されることはありません。このツールには read_builds と read_build_logs のスコープが必要です。さらに調査するには get_build_failure_summary または tail_logs を使用してください。失敗したステップが共通していても、根本原因が同じであることや、安全に再試行できることの証明にはなりません。

ベースラインの検出では、候補を最大 500 件検索します。見つからない場合、比較が実行されなかったことと、明示的なベースラインを指定するよう求めるメッセージが返されます。各ビルドのジョブ一覧は 1,000 件までです。これを超える場合、誤解を招く部分的な追加／削除結果を返す代わりにエラーになります。出力から省略された項目は、完全な結果数とは別に報告されます。

Test Engine ワークフローの調査

tests ツールセットに含まれる読み取り専用の list_test_workflows と get_test_workflow ツールでは、スイートに設定されたモニター、フィルター、アラーム／復旧アクション、リンクを確認できます。どちらのツールにも read_suites とスイートへのアクセス権が必要です。ワークフローを一覧表示するには、org_slug と test_suite_slug（スラッグまたは UUID）を指定します。

{"org_slug": "acme", "test_suite_slug": "backend"}

個別のワークフローを調べるには、同じ組織とスイートを指定して get_test_workflow を呼び出し、対象項目の id を workflow_id として渡します。

設定済みのラベルを list_tests とともに使用して、マークされたテストを検索してください。ラベルだけでは不安定さの順位付けはできません。ワークフローが示すのは設定内容であり、アクションが実行された証拠やイベント履歴ではありません。呼び出し元の API 権限にかかわらず、どちらのツールも Webhook エンドポイントを常に [REDACTED] に置き換えます。

Test Engine のスパン集計の調査

読み取り専用の tests ツールセットには、read_suites を必要とする 4 つのスパン集計ツールが含まれます。

  • list_span_aggregate_scopes：org_slug、test_suite_slug、および任意の period を指定すると、合計時間順にインストルメンテーションスコープを一覧表示します。OTel トレースの取り込みが有効になっている必要があります。集計の精度は 1 時間単位で、保持期間は 1 か月です。指定期間は、組織の API 履歴の許容範囲内である必要があります。
  • list_span_aggregate_scopes_for_build：org_slug と build_uuid を指定すると、ビルドから参照可能なスイート全体のインストルメンテーションスコープを一覧表示します。OTel トレースの取り込みと、ビルドのパイプラインへのアクセスが必要です。
  • list_span_aggregate_names：org_slug、test_suite_slug、scope_name を指定すると、スイートのスパン名統計を取得します。list_span_aggregate_scopes と同じ period の値と保持期間に加え、以下で説明する sort および limit オプションをサポートします。OTel トレースの取り込みが必要です。
  • list_span_aggregate_names_for_build：org_slug、build_uuid（パイプラインのビルド番号ではありません）、scope_name を指定すると、ビルドから参照可能なスイート全体のスパン名統計を取得します。名前のないスコープには空文字列を使用してください。ビルドのパイプラインへのアクセスが必要です。任意の sort のデフォルト値は -total です。limit のデフォルト値は 20（最大 100）です。結果を完全なものとして扱う前に span_names_truncated を確認してください。

時間はナノ秒単位です。合計値はスパンの時間を合算したものであり、実時間を測定したものではありません。p50 と p95 の値は概算です。スパン集計ツールはページネーションに対応していません。どちらのスパン名ツールも、名前のないスコープには空の scope_name を指定でき、名前がさらに存在する場合は span_names_truncated を返します。

ライブラリの使用

このモジュールのエクスポートされた Go API は、プロジェクトの進化に伴って破壊的変更が加わる可能性があるため、不安定なものとして扱ってください。

セキュリティ

MCP サーバーを安全な環境で実行するため、コンテナ内での実行を推奨します。

このイメージは cgr.dev/chainguard/static をベースに構築されており、非特権ユーザーとして実行されます。

HTTP モードでの ID ヘッダーの転送

セルフホストの HTTP デプロイでは、受信した各 MCP リクエストから選択したヘッダーを Buildkite API に転送できます。

BUILDKITE_API_TOKEN=bkua_xxx \
  buildkite-mcp-server http \
  --passthrough-http-header X-User-Identity

複数のヘッダーを許可するには --passthrough-http-header を繰り返すか、カンマ区切りの BUILDKITE_PASSTHROUGH_HTTP_HEADERS 値を設定してください。明示的に許可されたヘッダーのみが、BUILDKITE_BASE_URL で設定されたオリジンにのみ転送されます。別の場所にリダイレクトされたリクエストからは削除されます。

各 MCP リクエストをそれぞれの Buildkite API トークンで認証するには、Authorization を許可し、プロセス全体で使用するトークンを省略してください。

BUILDKITE_PASSTHROUGH_HTTP_HEADERS=Authorization \
  buildkite-mcp-server http

このモードでは、すべての /mcp リクエストに、空でない Authorization ヘッダーがちょうど 1 つ含まれている必要があります。認証情報がない場合は HTTP 401 が返され、サーバーが共有 API トークンにフォールバックすることはありません。MCP サーバーの前段にあるリバースプロキシは、呼び出し元の認証と、転送する ID ヘッダーの設定または検証を担当します。 stdio モードではヘッダーのパススルーを利用できません。ジョブログを提供する前に、サーバーは現在の呼び出し元がジョブログにアクセスできることを確認します。この確認は、ログデータがすでにキャッシュされている場合も含め、ログツールへのリクエストごとに実行されます。

貢献

開発ガイドラインはDEVELOPMENT.mdに記載されています。

ライセンス

MIT © Buildkite

SPDX-License-Identifier: MIT