buildkite-pipelines

Buildkite パイプライン

パイプライン YAML は Buildkite CI/CD の中核です。このスキルでは、.buildkite/pipeline.yml の作成、最適化、トラブルシューティングについて、ステップの種類、キャッシュ、並列処理、アノテーション、再試行、動的パイプライン、マトリックスビルド、プラグイン、通知、アーティファクト、同時実行を解説します。

クイックスタート

リポジトリのルートに .buildkite/pipeline.yml を作成します。

steps:
  - label: ":hammer: Tests"
    command: "npm test"
    artifact_paths: "coverage/**/*"

  - wait

  - label: ":rocket: Deploy"
    command: "scripts/deploy.sh"
    branches: "main"

Buildkite でパイプラインの初期コマンドを設定し、このファイルをアップロードします。

steps:
  - label: ":pipeline: Upload"
    command: buildkite-agent pipeline upload

エージェントは .buildkite/pipeline.yml を読み込み、実行するステップを Buildkite にアップロードします。

Buildkite はデフォルトで .buildkite/pipeline.yml を探します。buildkite-agent pipeline upload path/to/other.yml を使うと、パスを変更できます。

パイプラインをプログラムで作成する方法については、buildkite-api スキルを参照してください。 エージェントとキューの設定については、キューのドキュメントを参照してください。

ステップの種類

種類	用途	最小構文
command	シェルコマンドを実行する	- command: "make test"
wait	直前のすべてのステップが成功するまで待機する	- wait
block	手動承認のために一時停止する	- block: ":shipit: Release"
trigger	別のパイプラインでビルドを開始する	- trigger: "deploy-pipeline"
group	ステップを視覚的にグループ化する（折りたたみ可能）	ネストした steps: を持つ - group: "Tests"
input	続行する前にユーザー入力を収集する	fields: を持つ - input: "Release version"

各ステップの種類の詳細な属性と応用例については、references/step-types-reference.md を参照してください。

キャッシュ

依存関係のキャッシュは、最も効果の高い最適化です。マニフェストベースの無効化に対応したキャッシュプラグインを使用します。

steps:
  - label: ":nodejs: Test"
    command: "npm ci && npm test"
    plugins:
      - cache#v1.8.1:
          paths:
            - "node_modules/"
          manifest: "package-lock.json"

キャッシュキーはマニフェストファイルのハッシュから生成されます。package-lock.json が変更されると、キャッシュが再構築されます。

ホステッドエージェントは、組み込みの cache キーにも対応しています（プラグインは不要です）。

steps:
  - label: ":nodejs: Test"
    command: "npm ci && npm test"
    cache:
      paths:
        - "node_modules/"
      key: "v1-deps-{{ checksum 'package-lock.json' }}"

ホステッドエージェントの設定とインスタンスの種類については、Buildkite ホステッドエージェントのドキュメントを参照してください。

即時失敗と非ブロッキングステップ

いずれかのジョブが失敗したら、残りのジョブを直ちにキャンセルします。

steps:
  - label: ":rspec: Tests"
    command: "bundle exec rspec"
    cancel_on_build_failing: true

ビルドをブロックしないステップ（セキュリティスキャン、リンティング、カバレッジなど）には soft_fail を使用します。

steps:
  - label: ":shield: Security Scan"
    command: "scripts/security-scan.sh"
    soft_fail:
      - exit_status: 1

ソフト失敗したステップは UI で警告として表示されますが、ビルドは失敗しません。wait ステップに continue_on_failure: true を組み合わせると、後続のステップを失敗にかかわらず実行できます。

並列処理と依存関係

並列実行

同じ階層にあるステップは、デフォルトで並列実行されます。parallelism を使用して、単一のステップを複数に分割できます。

steps:
  - label: ":rspec: Tests %n"
    command: "bundle exec rspec"
    parallelism: 10

これにより、10 個の並列ジョブが作成されます。各ジョブには、作業を分割するための環境変数として BUILDKITE_PARALLEL_JOB（0～9）と BUILDKITE_PARALLEL_JOB_COUNT（10）が渡されます。

実行時間データに基づくインテリジェントなテスト分割については、buildkite-test-engine スキルを参照してください。

明示的な依存関係

wait を使わずにステップレベルの依存関係を表現するには、depends_on を使用します。

steps:
  - label: "Build"
    key: "build"
    command: "make build"

  - label: "Unit Tests"
    depends_on: "build"
    command: "make test-unit"

  - label: "Integration Tests"
    depends_on: "build"
    command: "make test-integration"

ビルドの完了後、ユニットテストと統合テストは並列実行されます。wait ステップは必要ありません。

アノテーション

buildkite-agent annotate を使用して、ビルドページにビルド結果を直接表示します。Markdown と HTML に対応しています。

steps:
  - label: ":test_tube: Tests"
    command: |
      if ! make test 2>&1 | tee test-output.txt; then
        buildkite-agent annotate --style "error" --context "test-failures" < test-output.txt
        exit 1
      fi
      buildkite-agent annotate "All tests passed :white_check_mark:" --style "success" --context "test-results"

フラグ	デフォルト	説明
--style	default	表示スタイル：default、info、warning、error、success
--context	random	一意の ID。同じ context を再利用すると、アノテーションが置き換えられます
--append	false	同じ context の既存のアノテーションに追記します

アノテーションからアップロード済みのアーティファクトにリンクします。

- command: |
    buildkite-agent artifact upload "coverage/*"
    buildkite-agent annotate --style "info" 'Coverage: <a href="artifact://coverage/index.html">view report</a>'

再試行

自動再試行

終了ステータスに基づいて、一時的な失敗を再試行します。

steps:
  - label: ":hammer: Build"
    command: "make build"
    retry:
      automatic:
        - exit_status: -1    # Agent lost
          limit: 2
        - exit_status: 143   # SIGTERM (spot instance termination)
          limit: 2
        - exit_status: 255   # Timeout or SSH failure
          limit: 2
        - exit_status: "*"   # Any non-zero exit
          limit: 1

手動再試行

手動での再試行を許可するかどうかを制御します。

retry:
  manual:
    allowed: false
    reason: "Deployment steps cannot be retried"

終了コードの一覧と再試行戦略の推奨事項については、references/retry-and-error-codes.md を参照してください。

動的パイプライン

リポジトリの状態に基づいて、実行時にパイプラインのステップを生成します。生成した YAML を buildkite-agent pipeline upload でアップロードします。

steps:
  - label: ":pipeline: Generate"
    command: |
      .buildkite/generate-pipeline.sh | buildkite-agent pipeline upload

どの方法を使うべきか

パイプラインにはさまざまな段階があります。目的を達成できる最もシンプルな方法を選んでください。

状況	方法
毎回のビルドで手順が同じで、ブランチレベルのフィルタリングだけで十分な場合	静的 YAML
パイプライン構造を組織全体で適用し、管理者が制御する場合（Enterprise プラン）	パイプラインテンプレート
多数のパイプラインで共有する、再利用可能で検証済みのロジック（キャッシュ、Docker、アーティファクト転送）	固定バージョンのプラグイン
特定のファイルに変更がない場合に手順をスキップする	if_changed
サービスごとに個別のパイプラインがあるモノレポ	monorepo-diff プラグイン
if と if_changed を OR 条件で組み合わせる	動的生成
多数のパイプラインに一貫した再試行／タイムアウト／環境設定を適用する	動的（共有設定）
テストのシャード、マトリックスの組み合わせ、実行時の parallelism × matrix を計算する	動的（多くの場合、SDK を使用）
サービス間に推移的な依存関係があるモノレポ	動的（カスタム依存関係グラフ）
インフラ障害から復旧する（OOM → より大きなエージェント）	動的（pre-exit フック）
前の手順の出力に依存するステップ（複数ステージ）	動的。多くの場合、--replace または連鎖アップロードを使用
それ以前の失敗に関係なく必ず実行するクリーンアップ／ティアダウンステップ	動的（pre-exit でファイナライザーをアップロード）
主要なステップが失敗した場合にのみ実行するフォールバックステップ	動的（pre-exit で終了ステータスを確認）
パイプライン YAML がチームで管理できる範囲を超えている	動的（Python／TS／Go／Ruby の SDK）

動的パイプラインを目的違いで使わないでください

動的生成は、ステップ自体を変更する必要がある場合に適した方法です。ステップ間でデータを渡すだけなら、もっとシンプルな方法があります。

• buildkite-agent meta-data set/get — 後続のステップが同じビルド内で読み取れる、小さなキーと値のペア（バージョン文字列、コミット SHA、機能フラグなど）。
• アーティファクト — ステップ間で受け渡すファイル（buildkite-agent artifact upload/download）。
• トリガーステップの env: — 別のパイプラインのビルドに渡す環境変数。

移動させる必要があるのがデータだけなら、メタデータやアーティファクトを使うほうがシンプルで安全です。buildkite-agent-runtime スキルを参照してください。

ブートストラップスクリプト

ジェネレータースクリプトは必ず set -euo pipefail で始めてください。 pipefail がないと、pipeline upload が失敗しても、パイプでつながれた最後のコマンドの終了コードが返されます。その結果、ビルドステップが成功と報告され、生成されたステップが表示されません。これは動的パイプラインで最もよくある失敗パターンです。

変更されたサービスだけをテストするジェネレーターの例：

#!/bin/bash
set -euo pipefail
CHANGED=$(git diff --name-only HEAD~1)
cat <<YAML
steps:
YAML
for dir in services/*/; do
  svc=$(basename "$dir")
  if echo "$CHANGED" | grep -q "^services/$svc/"; then
    cat <<YAML
  - label: ":test_tube: $svc"
    command: "cd services/$svc && make test"
    key: "test-$svc"
YAML
  fi
done

生成する各ステップに key: を設定してください。これにより depends_on が使えるようになり、再試行の冪等性が保たれ（アップロードステップが再実行された際に DuplicateKeyError によって重複が黙って作成されるのを防ぎます）、ビルド間で安定した識別子が得られます。プッシュする前に、buildkite-agent pipeline upload --dry-run を使ってローカルで検証してください。

1 回のアップロードは500 ステップ未満、1 ビルドあたりのジョブ数は4,000 件未満にしてください（プラットフォームの既定値です。サポートに問い合わせることで引き上げられます）。さらに規模の大きなモノレポでは、トリガーステップを使って複数のビルドに処理を分散してください。

型チェックとユニットテストに対応するジェネレーターには、Buildkite SDK が JavaScript／TypeScript、Python、Go、Ruby をサポートしています。ジェネレーターが約 10 ステップを超える場合は、関連するステップをグループステップでまとめてください。グループを追加するとビルドで DAG モードが有効になり、グループでは concurrency 属性が拒否されます（references/group-steps.md を参照）。

ジェネレーターステップは、実行時の状態（メタデータ、アーティファクト、git diff）を読み取り、パイプラインの次のフェーズをアップロードすることもできます。これは複数ステージのビルドで使われるハンドラーパターンです。このパターン、ファンアウト／ファンイン、pre-exit フックによるファイナライザー／常時実行ステップについては、references/dynamic-pipeline-patterns.md を参照してください。失敗パターンについては、references/dynamic-pipeline-troubleshooting.md を参照してください。高度なジェネレーターパターン（Python、モノレポ、複数ステージ）については、references/advanced-patterns.md を参照してください。

条件付き実行

ステップレベルの条件

ビルドの状態に基づいてステップを条件付きで実行するには、if を使用します。

steps:
  - label: ":rocket: Deploy"
    command: "scripts/deploy.sh"
    if: build.branch == "main" && build.message !~ /\[skip deploy\]/

条件式の一覧については、条件式を参照してください。

[skip ci] に関する注意点： Buildkite が確認するのは HEAD コミットのメッセージのみで、[skip ci] / [ci skip] が含まれているかを判定します。複数のコミットをまとめてプッシュした際に、タグがそれより前のコミットに含まれていても、ビルドはトリガーされます。

ディレクトリベースのステップフィルタリング（if_changed）

関連ファイルに変更がない場合はステップをスキップします。パイプラインのアップロード時に Buildkite エージェントによってのみ適用されます。https://buildkite.com/docs/pipelines/configure/dynamic-pipelines/if-changed.md を参照してください。

steps:
  - label: ":nodejs: Frontend tests"
    command: "npm test"
    if_changed:
      - "src/frontend/**"
      - "package.json"

除外パターンとモノレポの設定については、references/advanced-patterns.md を参照してください。

大規模なモノレポでは、Sparse Checkout plugin を使用してアップロードステップでは .buildkite/ のみをチェックアウトすると、パイプラインのアップロードを大幅に高速化できます。

プラグインの条件付き実行

ステップレベルの if では、プラグインの実行を防げません。プラグインを完全にスキップするには、ステップを group で囲みます。

steps:
  - group: ":docker: Build"
    if: build.env("DOCKER_PASSWORD") != null
    steps:
      - label: "Build image"
        command: "docker build -t myapp ."
        plugins:
          - docker-login#v2.1.0:
              username: myuser
              password-env: DOCKER_PASSWORD

マトリックスビルド

同じステップを複数の設定で実行します。

steps:
  - label: "Test {{matrix.ruby}} on {{matrix.os}}"
    command: "bundle exec rake test"
    matrix:
      setup:
        ruby:
          - "3.2"
          - "3.3"
        os:
          - "ubuntu"
          - "alpine"
      adjustments:
        - with:
            ruby: "3.2"
            os: "alpine"
          skip: true  # Known incompatible

各 adjustments エントリ内で有効なプロパティは、with、skip、soft_fail、env です。agents: キーは adjustments 内では無効です。Buildkite は「agents is not a valid property on the matrix.adjustments configuration」というエラーでパイプラインを拒否します。マトリックスの組み合わせを異なるキュー（例：Linux と Windows のエージェント）に振り分けるには、個別のステップを使用するか、動的パイプラインジェネレーターを使用してください。

プラグイン

3 行の YAML ブロックで機能を追加します。再現性を確保するため、バージョンを固定してください。

plugins:
  - docker-compose#v5.5.0:
      run: app
      config: docker-compose.ci.yml

プラグイン	用途
cache#v1.8.1	マニフェストベースの無効化による依存関係のキャッシュ
docker#v5.12.0	Docker コンテナー内でステップを実行
docker-compose#v5.5.0	Docker Compose でビルドと実行
artifacts#v1.9.4	ステップ間でアーティファクトをダウンロード
test-collector#v2.0.0	テスト結果を Test Engine にアップロード

プラグインのバージョンは必ず固定してください（例：docker#v5 ではなく docker#v5.12.0）。バージョンを固定しないと、プラグインが新しいメジャーバージョンをリリースした際にビルドが失敗する可能性があります。

非公開の組織内プラグインには、完全な Git URL を使用してください。省略形の構文が使えるのは公開プラグインのみです。

plugins:
  - ssh://[email protected]/my-org/my-plugin.git#v1.0.0:
      config: value

通知とアーティファクト

パイプラインレベルの notify: を steps: より上に追加すると、ビルドの状態が変化した際に Slack、メール、または Webhook で通知できます。構文については通知を参照してください。

アーティファクトのアップロードとダウンロード

ステップからアーティファクトをアップロードし、後続のステップでダウンロードします。

steps:
  - label: "Build"
    command: "make build"
    artifact_paths: "dist/**/*"

  - wait

  - label: "Package"
    command: |
      buildkite-agent artifact download "dist/*" .
      make package

Docker ビルドでアーティファクトを使用する場合、buildkite-agent はコンテナー内で利用できないため、Docker ビルドを開始する前にアーティファクトをダウンロードしてください。

steps:
  - label: "Docker build"
    command: |
      buildkite-agent artifact download "dist/*" .
      docker build -t myapp .

並行実行

リソースを共有するステップの並行実行数を制限します。concurrency には必ず concurrency_group を設定してください。グループ名がない場合、制限は警告なしに無視されます。

steps:
  - label: ":rocket: Deploy"
    command: "scripts/deploy.sh"
    concurrency: 1
    concurrency_group: "deploy/production"
    concurrency_method: "eager"

デプロイなどの独立したジョブには、次に実行可能なジョブを優先する concurrency_method: "eager" を使用します。実行順序が重要な場合は、デフォルトの "ordered"（FIFO）を使用します。priority（デフォルトは 0。値が大きいほど優先）を設定すると、キューに入ったジョブの実行順を制御できます。

並行実行の設定オプションについて詳しくは、並行実行の制御を参照してください。

ターミナルからのパイプラインのトリガー、監視、デバッグについては、buildkite-cli スキルを参照してください。

よくある間違い

間違い	起こること	対処法
依存するステップ間に wait がない	ステップが並列実行され、最初のステップが終わる前に2番目のステップが実行されるため失敗します	- wait を追加するか、depends_on: を使用します
すべての依存関係に wait ステップだけを使用する	有効ですが、一般的な方法ではありません。wait はそれ以前のすべてのステップをブロックするため、独立したステップを並列実行できなくなります	名前付きステップに key: を指定し、細かな依存関係を表すために depends_on: "key" を使用します。無条件のバリアには wait を使用します
パッケージのインストール手順があるパイプラインに plugins: がない	ビルドごとに依存関係を最初から再インストールするため、ビルドが遅くなり、コストも増加します	cache プラグイン（またはホストエージェント向けの組み込み cache: キー）を追加して、node_modules/、.gradle/ などをキャッシュします。上記のキャッシュのセクションを参照してください
プラグインのスキップにステップレベルの if を使用する	プラグインは引き続き実行されます（if の評価前に実行されるためです）	if 条件を指定した group で囲みます
プラグインのバージョンを固定しない	プラグインの破壊的変更を含むリリースにより、ビルドが失敗します	常に完全なセマンティックバージョンを指定します：plugin#v1.2.3
concurrency に concurrency_group を指定し忘れる	グループ名がないと concurrency は無視されます	必ず concurrency と concurrency_group を併せて指定します
artifact_paths の glob が出力に一致しない	アーティファクトが通知なくアップロードされず、後続のステップが失敗します	glob パターンをローカルでテストします。ネストされたディレクトリには **/* を使用します
並列ジョブの分割ロジックをハードコーディングする	テストの分配が不均衡になり、遅いジョブが1つあるだけでビルドが遅延します	Test Engine による実行時間ベースの分割で parallelism: N を使用します
パイプライン YAML にシークレットを直接記述する	ビルドログや Buildkite UI からシークレットを確認できてしまいます	クラスターシークレットまたはエージェントの環境フックを使用します
exit_status: "*" と高い上限値を指定して retry.automatic を使用する	実際のバグが繰り返し再試行され、コンピューティングリソースが無駄になります	特定の終了コードを対象にし、ワイルドカードの上限は1にします
matrix.adjustments 内で agents: を使用する	パイプラインのアップロードが失敗します：「agents is not a valid property on the matrix.adjustments configuration」	adjustments から agents: を削除します。プラットフォームごとに個別のステップを使用するか、組み合わせごとのキュー振り分けには動的パイプラインジェネレーターを使用します
ビルドは失敗したのに、表示されているすべてのステップが成功している	トリガーステップが失敗した子パイプラインを開始したか、ステップがブロック解除されずにキャンセルされています	トリガーされたパイプラインのビルドステータスを確認し、ブロックステップがキャンセルされていないか調べます
明確なエラーがないままパイプラインのアップロードが失敗する	YAML 構文エラー、またはビルドログに表示されないエージェント側の問題です	YAML をローカルで検証します。詳細なアップロードエラーについてはホストマシンのエージェントログを確認し、buildkite-agent pipeline upload --debug を実行します
公開パイプラインでフォークビルドが有効になっている	コントリビューターが pipeline.yml を変更し、シークレットを抜き出せる可能性があります	公開リポジトリではパイプライン設定でフォークビルドを無効にします。シークレットにアクセスできない外部 PR 用の別パイプラインを使用します
Docker Compose のステップでアーティファクトが生成されるが、エージェントが見つけられない	コンテナー内で作成されたファイルはホストエージェントから見えません	docker-compose.yml で作業ディレクトリをボリュームとしてマウントし、コンテナーの出力を artifact_paths: から見えるようにします
動的パイプラインが1000以上のステップを生成する	UI が遅くなり、パイプラインの処理性能が低下します	生成するパイプラインは約500ステップ未満に抑えます。より大規模なモノレポでは、トリガーステップを含むオーケストレーターパイプラインを使用します

追加リソース

参考ファイル

• references/step-types-reference.md — すべてのステップタイプの詳細な属性テーブル
• references/advanced-patterns.md — 動的パイプラインジェネレーター、マトリックスの調整、モノレポのパターン、マルチステージパイプライン
• references/retry-and-error-codes.md — 終了コードの包括的なテーブル、失敗の種類ごとの再試行戦略
• references/group-steps.md — グループステップの属性、DAG モード、アップロード間のマージ、ネスト不可への対処法、ジョブ数上限への影響
• references/dynamic-pipeline-troubleshooting.md — アップロードが通知なく失敗する問題、クォータの上限、環境変数の補間、再試行時の重複、再試行の集中
• references/dynamic-pipeline-patterns.md — ファンアウト／ファンイン、SDK 生成、ハンドラーパターン、ファイナライザーステップ、トリガーベースのファンアウト

例

• examples/basic-pipeline.yml — 最小構成の動作するパイプライン（テスト、待機、デプロイ）
• examples/optimized-pipeline.yml — キャッシュ、並列処理、アノテーション、再試行、アーティファクト、通知を備えたフル機能のパイプライン

他の CI システムからパイプラインを移行する場合は、buildkite-migration スキルを参照してください。

さらに詳しく

• LLM 向け Buildkite ドキュメント
• パイプラインステップの定義
• ステップタイプのリファレンス
• パイプラインのアップロード
• 条件文
• パイプラインシークレットの管理
• パイプライン設計のベストプラクティス