buildkite-preflight

Buildkite Preflight

Preflight は、ローカルの作業ツリーの変更を対象に CI ビルドを実行します。CI でローカルの変更を評価するためのフィードバックループを提供することを目的としており、コミット、プッシュ、実行までの一連の流れを 1 つのコマンドで実行できます。

Preflight を実行するタイミング

• 要求された実装を完了し、ローカルテストに合格した後、CI でテストスイート全体を実行するために preflight を使用します
• 複数の変更を加えた場合、長時間の無人セッションを終了する前に実行します
• 前回の preflight 実行で発生した失敗を修正した後に実行します
• ユーザーから依頼がない限り、誤字、コメントのみの編集、1 行の設定変更などの軽微な変更では実行しません
• ユーザーから CI で変更が機能することを確認するよう依頼された場合に実行します

実行前の準備

• {org}/{pipeline} の形式で明示的なパイプラインを指定することを推奨します
• パイプラインのスラッグがローカル設定に依存する場合は、bk auth が正しい Buildkite 組織を参照していることを確認します
• 少なくとも 1 つのコミットがある Git リポジトリと、origin へのプッシュ権限が必要です
• read_builds、write_builds、read_pipelines のスコープが必要です。Test Engine の結果には read_suites も必要です。
• preflight はサブエージェントで実行します

Preflight の実行

# Human-readable output that works well in agent shells
bk preflight --pipeline my-org/my-pipeline --watch --text

# Start a run and return as soon as the build enters the failing state
bk preflight --pipeline my-org/my-pipeline --watch

# Wait for a terminal build state instead of fast-failing
bk preflight --pipeline my-org/my-pipeline --watch --exit-on=build-terminal

# Start the build and exit immediately
bk preflight --pipeline my-org/my-pipeline --no-watch

# Leave the remote preflight branch and build running on early exit
bk preflight --pipeline my-org/my-pipeline --watch --no-cleanup

# Wait for 30s after build completion for Test Engine summaries
bk preflight --pipeline my-org/my-pipeline --watch --await-test-results 30s

監視対象の preflight 実行にはタイムアウトを設定しないでください。

動作の仕組み

Preflight は次のワークフローを実行します。

1. スナップショット - 一時的な Git インデックスを使用して、ステージ済み、未ステージ、未追跡のファイルを取得します。実際のインデックスや作業ツリーは変更しません。
2. コミット - 作業ツリーに変更がない場合も含め、HEAD の上に独立した preflight コミットを作成します。これにより、実行に固有のコミットステータスコンテキストが得られます。
3. プッシュ - そのコミットを origin の refs/heads/bk/preflight/<uuid> にプッシュします。
4. ビルドの作成 - Buildkite Create Build API を呼び出し、利用可能な場合は PREFLIGHT=true、PREFLIGHT_SOURCE_COMMIT、PREFLIGHT_SOURCE_BRANCH を設定します。
5. 監視 - ビルドを監視し、操作イベント、ビルドステータスの更新、ジョブの失敗、再試行後に成功したジョブ、最終サマリーを出力します。
6. クリーンアップ - 実行が終了すると、--no-cleanup が設定されていない限り、リモートの preflight ブランチを削除します。デフォルトの --exit-on=build-failing では、早期終了時にも --no-cleanup が設定されていない限り、リモートビルドをキャンセルします。

作業ツリーが変更されることはないため、ビルドの実行中も編集を続けられます。

結果の確認

• デフォルトの終了ポリシーは build-failing です。preflight コマンドは、ビルドが failing 状態になるとすぐに終了します。
• --exit-on=build-terminal は、ビルドが終端状態（passed、failed、canceled）になるまで待機します。
• --await-test-results は、テスト実行がある場合、ビルド完了後に Test Engine の集計結果が出るまで待機します。
• 最終的なジョブのサマリーには、ハード失敗したスクリプトジョブが含まれ、スクリプト以外のジョブ、破損したジョブ、ソフト失敗したジョブは含まれません
• 失敗したジョブの出力にはジョブ ID が含まれます。ログを確認するには、bk job log -b <build-number> -p <org>/<pipeline> <job-id> を使用します。
• アナリティクスを利用できる場合、最終サマリーにはスイートごとの成功、失敗、スキップの件数と、最大 10 件の失敗したテストが表示されます。
• テストの失敗にはテスト名と場所が含まれます。失敗をローカルで再現して修正してください。
• 失敗が不安定なテストや変更と無関係なものである場合は、修正しようとせず、その旨をユーザーに伝えてください。

JSON の build_summary イベントから結果を抽出する方法：

Just the failed jobs from the summary:

bk preflight --pipeline my-org/my-pipeline --watch --json \
  | jq -nrc --unbuffered 'inputs | select(.type == "build_summary") | .failed_jobs'

Just the failed tests from the summary:

bk preflight --pipeline my-org/my-pipeline --watch --json \
  | jq -nrc --unbuffered 'inputs | select(.type == "build_summary") | .tests.failures'

出力モード

• ツールの出力で読みやすいプレーンテキストログを表示するには、--text を使用します
• 構造化されたイベントデータが必要な場合は、--json を使用します
• どちらのフラグも設定されていない場合、標準出力が端末なら bk は対話型 TTY UI を使用し、それ以外ではプレーンテキストを出力します

Preflight ビルドの実行

基本的な使い方

# Run preflight and watch until completion
bk preflight --pipeline my-org/my-pipeline --watch

# Run without watching (starts the build and exits)
bk preflight --pipeline my-org/my-pipeline --no-watch

# Skip confirmation prompts (useful in scripts)
bk preflight --pipeline my-org/my-pipeline --watch --yes

# Keep the remote preflight branch after the build finishes
bk preflight --pipeline my-org/my-pipeline --watch --no-cleanup

# Use plain text output in non-interactive environments
bk preflight --pipeline my-org/my-pipeline --watch --text

# Use JSONL output when another tool needs structured events
bk preflight --pipeline my-org/my-pipeline --watch --json

# Wait for 10s for Test Engine results after build completion
bk preflight --pipeline my-org/my-pipeline --watch --await-test-results 10s

preflight を実行する bash ツールにはタイムアウトを設定しないでください。

パイプラインの解決

--pipeline フラグには、パイプラインのスラッグまたは {org slug}/{pipeline slug} を指定できます。

# With org prefix (explicit)
bk preflight --pipeline my-org/my-pipeline --watch

# Pipeline slug only (org resolved from bk config)
bk preflight --pipeline my-pipeline --watch

フラグ

フラグ	短縮形	デフォルト	説明
--pipeline	-p	-	ビルドするパイプライン（{slug} または {org}/{slug}）（必須）
--[no-]watch		-	完了するまでビルドを監視します
--exit-on		build-failing	build-failing または build-terminal で終了します
--interval		2	監視中のポーリング間隔（秒）
--no-cleanup		false	ビルド完了後にリモートのプリフライトブランチを削除しません
--await-test-results			ビルド完了後、Test Engine のサマリーを待ちます
--text		false	対話型 UI の代わりにプレーンテキストで出力します
--json		false	イベントごとに 1 つの JSON オブジェクトを出力します（JSONL）
--yes	-y	false	すべての確認プロンプトを省略します
--no-input		false	すべての対話型プロンプトを無効にします
--quiet	-q	false	進行状況の出力を抑制します
--no-pager		false	テキスト出力でページャーを無効にします
--debug		false	REST API 呼び出しのデバッグ出力を有効にします

終了コード

終了コードを確認して、ビルドの結果を判定します。

終了コード	意味	対応
0	すべてのコマンドジョブが成功しました	コミット／プッシュに進みます
1	一般的なエラー	詳細についてはエラーメッセージを確認します
9	ビルドが失敗して完了しました	失敗したジョブを確認して修正します
10	失敗が確認されましたが、ビルドは未完了です	ビルドはまだ実行中ですが、すでに失敗が検出されています
11	ビルドは未完了です（スケジュール済み／実行中／ブロック中）	ビルドはまだ完了していません
12	ビルドの状態が不明です	Buildkite でビルドを調査します
130	ユーザーが中断しました（Ctrl+C）	準備ができたら再実行します

詳細情報

• Buildkite CLI の概要
• CLI コマンドリファレンス
• CLI のインストール

オプションのワークフロー：失敗に対処し、後から再確認する

ビルドが失敗しており、プリフライトが未完了のビルド結果で終了したら、最初の失敗の修正をすぐに開始します。ビルドの実行中も同じビルドのサマリーを確認し、その後の失敗については失敗したジョブを直接クエリします。これにより、最初の失敗にすばやく対処しながら、並行してさらなる失敗の情報を集められます。ビルドが早期失敗でキャンセルされないように、bk preflight --no-cleanup オプションを使用します。

bk preflight --pipeline my-org/my-pipeline --watch --no-cleanup --text

bk preflight は、デフォルトの --exit-on=build-failing の動作により、ビルドが failing に移行するとすぐに戻ります。ビルドを完了まで実行し続けるには、--no-cleanup フラグを設定する必要があります。

ワークフロー：

1. ビルドが失敗するとプリフライトが終了するまで待ちます（デフォルトの --exit-on 条件）。
2. 失敗したビルドのジョブログとテストの失敗を調べ、すぐに問題の修正を開始します。
3. 実行出力に表示されるビルド番号またはプリフライト UUID を控えておきます。
4. ジョブ、アーティファクト、アノテーション、展開済みパイプラインの詳細をダウンロードせずに、ビルドの状態を確認します。失敗したジョブは REST List Jobs エンドポイントから個別にクエリします。

bk build view 429 -p my-org/my-pipeline --summary --text
bk job list --pipeline my-org/my-pipeline --build 429 --state failed --no-limit --text

5. ビルドが終了状態になり、リモートのプリフライトブランチが不要になったら、明示的にクリーンアップします。

bk preflight cleanup --pipeline my-org/my-pipeline --preflight-uuid <uuid> --yes --text

bk preflight cleanup が削除するのは完了済みのプリフライトブランチのみです。そのため、ビルド完了後に実行してください。