buildkite-agent-runtime

Buildkite Agent Runtime

buildkite-agent バイナリは、実行中のジョブステップから Buildkite を操作するサブコマンドを提供します。アノテーションの作成、アーティファクトのアップロード、ジョブ間での状態共有、動的パイプラインの生成、OIDC トークンのリクエストなどを実行できます。このスキルでは、ジョブ内で使うすべてのサブコマンドの構文、フラグ、使用パターンを説明します。

クイックスタート

テストを実行し、失敗をアノテーションとして表示し、カバレッジをアップロードし、後続のジョブで使う結果フラグを保存するステップです。

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
        buildkite-agent meta-data set "tests-passed" "false"
        exit 1
      fi
      buildkite-agent annotate "All tests passed :white_check_mark:" --style "success" --context "test-results"
      buildkite-agent artifact upload "coverage/**/*"
      buildkite-agent meta-data set "tests-passed" "true"

後続のステップでその状態を読み取ります。

  - label: ":rocket: Deploy"
    command: |
      PASSED=$(buildkite-agent meta-data get "tests-passed")
      if [[ "$PASSED" != "true" ]]; then
        echo "Tests did not pass, skipping deploy"
        exit 0
      fi
      scripts/deploy.sh
    depends_on: "test-step"

アノテーション

ビルドの結果をビルドページに直接表示します。アノテーションでは Markdown と HTML を使用できます。

アノテーションの作成

# Simple text annotation
buildkite-agent annotate "Deploy completed successfully" --style "success" --context "deploy"

# Pipe from a file
buildkite-agent annotate --style "error" --context "test-failures" < test-output.md

主なフラグ

フラグ	短縮形	デフォルト	説明
--style	-s	default	表示スタイル：default、info、warning、error、success
--context	-c	ランダムな UUID	一意の ID。同じ context を再利用するとアノテーションが置き換えられます
--append	—	false	置き換える代わりに、同じ context の既存アノテーションに追記します
--priority	—	3	表示優先度（1～10）。数値が大きいほど先に表示されます
--job	—	現在のジョブ	アノテーションを付けるジョブ ID（通常は不要です）

置き換えと追記

• 同じ --context を指定して --append を付けない場合はアノテーションが置き換えられ、--append を付けた場合は既存の内容の下に追記されます。
• 再実行時に重複を作成せず、同じアノテーションを更新できるよう、常に安定した --context の値を使用してください。

パイプラインレベルの notify: 設定については、buildkite-pipelines スキルを参照してください。

アーティファクト

ファイルをビルドアーティファクトとしてアップロードし、後続のステップや別のビルドでダウンロードしたり、glob で検索したりできます。

アップロード

# Upload a single file
buildkite-agent artifact upload "pkg/release.tar.gz"

# Upload with glob pattern
buildkite-agent artifact upload "dist/**/*"

ダウンロード

# Download to current directory
buildkite-agent artifact download "pkg/release.tar.gz" .

# Download from a specific step
buildkite-agent artifact download "dist/*" . --step "build-step"

検索

# List matching artifacts
buildkite-agent artifact search "pkg/*.tar.gz" --build "$BUILDKITE_BUILD_ID"

フラグの一覧については、references/flag-reference.md を参照してください。

宣言型の artifact_paths: YAML キーについては、buildkite-pipelines スキルを参照してください。bk artifact CLI コマンドについては、buildkite-cli スキルを参照してください。

メタデータ

ジョブ間で状態を共有するための、ビルド全体で使えるキーと値のストアです。あるジョブで値を設定し、同じビルド内の別のジョブから読み取れます。

設定

buildkite-agent meta-data set "release-version" "1.4.2"

取得

VERSION=$(buildkite-agent meta-data get "release-version")

キーが見つからない場合にゼロ以外の終了コードを返す代わりに、フォールバック値を返すには --default を使用します：buildkite-agent meta-data get "deploy-env" --default "staging"。

存在確認

# Returns exit code 0 if exists, 100 if not
if buildkite-agent meta-data exists "release-version"; then
  echo "Version already set"
fi

一般的なパターン

ブロックステップのフィールド値は、メタデータとして自動的に保存されます。フィールドキーを指定して取得できます。

# After a block step with fields: [{key: "release-name", text: "Release Name"}]
RELEASE_NAME=$(buildkite-agent meta-data get "release-name")

Webhook の生ペイロードは、Webhook がキャッシュされている間、Webhook によってトリガーされたビルドで利用できます。元のプルリクエストコメント本文など、ファーストクラスの環境変数に昇格されていないフィールドが自動化で必要な場合は、特殊な buildkite:webhook キーを読み取ります。

WEBHOOK="$(buildkite-agent meta-data get "buildkite:webhook")"
COMMENT_BODY="$(jq -r '.comment.body' <<< "$WEBHOOK")"

パイプラインのアップロード

実行中のビルドにステップを動的に追加します。これは動的パイプラインの中核となる仕組みで、実行時に YAML を生成してアップロードします。

基本的な使い方

# Upload a specific file
buildkite-agent pipeline upload .buildkite/deploy-steps.yml

# Pipe generated YAML from stdin
./scripts/generate-pipeline.sh | buildkite-agent pipeline upload

置き換えモード

デフォルトでは、アップロードしたステップは現在のステップの後に追加されます。--replace を指定すると、残りのパイプライン全体を置き換えられます。

# Replace all remaining steps with the uploaded ones
buildkite-agent pipeline upload --replace .buildkite/new-pipeline.yml

主なフラグ

フラグ	デフォルト	説明
--replace	false	追加する代わりに、残りのパイプラインステップを置き換えます
--no-interpolation	false	アップロードする YAML の環境変数の補間をスキップします
--dry-run	false	パイプラインをアップロードせずに検証し、出力します

パイプライン YAML の構文とステップの種類については、buildkite-pipelines スキルを参照してください。

OIDC トークン

静的な認証情報を使わずに外部サービス（クラウドプロバイダー、パッケージレジストリ）を認証するため、ジョブステップから有効期間の短い OpenID Connect トークンをリクエストします。

基本的なトークンのリクエスト

# Request a token for a specific audience
TOKEN=$(buildkite-agent oidc request-token --audience "https://packages.buildkite.com/my-org/my-registry")

クラウドプロバイダーの認証

# AWS — request token with STS audience
TOKEN=$(buildkite-agent oidc request-token --audience "sts.amazonaws.com")

主なフラグ

フラグ	デフォルト	説明
--audience	Buildkite endpoint	対象サービスの URL — OIDC プロバイダーのオーディエンス設定と一致する必要があります
--lifetime	0 (API default)	トークンの有効期間（秒）。0 または省略した場合、API がデフォルトの有効期間を選択します
--claim	—	含める任意のクレーム（例：organization_id,pipeline_id）。繰り返し指定できます
--aws-session-tag	—	AWS セッションタグとしてマッピングするクレーム。繰り返し指定できます

エンドツーエンドの OIDC 認証フロー、クラウドプロバイダーのセットアップ、トークンのクレームの詳細については、buildkite-secure-delivery スキルを参照してください。

ステップ管理

実行時にステップの属性を読み取ったり変更したりできます。ステップ内の条件分岐やビルドの自動化に役立ちます。

ステップ属性を取得する

# Get a step's label (--step is required)
LABEL=$(buildkite-agent step get "label" --step "$BUILDKITE_STEP_KEY")

# Get another step's state
STATE=$(buildkite-agent step get "state" --step "deploy-step")

# Get the entire step as JSON
buildkite-agent step get --step "test-step" --format json

ステップ属性を更新する

# Update a step's label dynamically
buildkite-agent step update "label" ":rocket: Deploying v${VERSION}" --step "$BUILDKITE_STEP_KEY"

# Append to an existing label
buildkite-agent step update "label" " (retried)" --step "build-step" --append

ステップをキャンセルする

# Cancel all unfinished jobs for a step
buildkite-agent step cancel --step "optional-step"

# Force-cancel a running step
buildkite-agent step cancel --step "stuck-step" --force

主なフラグ

フラグ	デフォルト	説明
--step	—	対象のステップキーまたは UUID（必須 — $BUILDKITE_STEP_ID 環境変数が設定されている場合はそれを使用します）
--build	current build	ビルド UUID（ビルドをまたぐ操作用）
--format	—	get の出力形式（複雑な属性には json を使用してください）
--append	false	既存の値を置き換えずに追記します（step update のみ）
--force	false	ステップの実行中でも強制的にキャンセルします（step cancel のみ）

分散ロック

分散ミューテックスロックを使用して、ビルド内の並列ジョブを調整します。複数のジョブが共有リソースにアクセスする際の競合状態を防ぎます。

取得／解放パターン

#!/bin/bash
set -euo pipefail

# Acquire lock — blocks until available, returns a token
token=$(buildkite-agent lock acquire "database-migration")
trap 'buildkite-agent lock release "database-migration" "${token}"' EXIT

# Critical section — only one job runs this at a time
bundle exec rails db:migrate

Do／done パターン（一度限りのセットアップ）

すべての並列ジョブ間でセットアップタスクを正確に一度だけ実行します。

#!/bin/bash
echo "+++ Setting up shared test environment"

if [[ $(buildkite-agent lock do "test-env-setup") == "do" ]]; then
  echo "Downloading test assets..."
  curl -o /tmp/test-data.zip https://releases.example.com/data.zip
  unzip /tmp/test-data.zip -d /tmp/shared-test-files/
  buildkite-agent lock done "test-env-setup"
else
  echo "Assets already prepared by another job"
fi

# All jobs continue here
run-tests.sh

主なフラグ

サブコマンド	フラグ	説明
lock acquire <name>	--lock-wait-timeout	最大待機時間（例：30s、5m）。デフォルトでは無期限に待機します
lock release <name> <token>	—	acquire で取得したトークンを使って解放します
lock do <name>	—	ロックを取得した場合は do、すでに完了している場合は done を返します
lock done <name>	—	do ロックを完了としてマークします

環境

ジョブの環境変数を確認および変更します。主に、ライフサイクルフックのデバッグや、フックによる環境の変更内容の把握に役立ちます。

# Dump all environment variables as JSON
buildkite-agent env dump | jq .

# Get a specific variable
buildkite-agent env get "BUILDKITE_BRANCH"

# Set variables for subsequent hooks and the command (KEY=value format)
buildkite-agent env set DEPLOY_TARGET=production "APP_NAME=My App"

主なフラグ

サブコマンド	説明
env dump	すべての環境変数を出力します（デフォルトの形式は JSON です）
env get <keys...>	1 つ以上の特定の変数を取得します。出力形式には --format（plain、json、json-pretty）を使用してください
env set KEY=value [...]	後続のフェーズで使用する変数を設定します。複数の KEY=value ペアを指定できます
env unset <key>	後続のフェーズから変数を削除します

フックのデバッグ

env dump コマンドは、先行するフックによる変更内容を確認するために、ライフサイクルフック内で特に役立ちます。

#!/bin/bash
# .buildkite/hooks/pre-command
echo "--- Environment after environment hook:"
buildkite-agent env dump | jq 'keys'

エージェントのライフサイクルフックと buildkite-agent.cfg の設定については、エージェントフックおよびエージェントの設定のドキュメントを参照してください。

シークレット

ジョブのステップ内から、実行時にクラスターのシークレットを取得します。この方法で取得したシークレットは、自動的にログのレダクターに追加されます。

基本的な使い方

# Get a secret value
SECRET_VAR=$(buildkite-agent secret get "deploy-key")

# Pass directly to a tool
cli-tool --token "$(buildkite-agent secret get "api-token")"

主なフラグ

フラグ	デフォルト	説明
--format	default	出力形式：default（シークレットが1つの場合は値を出力し、複数の場合はJSONを出力）、json、または env（KEY="value" のペア）
--skip-redaction	false	シークレットの値をログレダクターに追加しません
--job	現在のジョブ	ジョブ ID のコンテキスト

複数のシークレットキーを一度に要求できます：buildkite-agent secret get KEY1 KEY2 KEY3。

デフォルトでは、secret get は取得した値を自動的にログレダクターに登録し、それ以降の出力で [REDACTED] としてマスキングします。

クラスターシークレットの設定については、Buildkite Secrets のドキュメントを参照してください。宣言型の secrets: パイプライン YAML キーについては、buildkite-pipelines スキルを参照してください。

ログのレダクション

実行時にビルドログのレダクターに値を追加すると、それ以降のすべての出力でマスキングされます。secrets: や buildkite-agent secret get で宣言されていない、動的に取得したシークレットに使用します。

基本的な使い方

# Fetch a token from an external source
DYNAMIC_TOKEN=$(curl -s https://vault.example.com/token)

# Register it with the redactor before using it
echo "$DYNAMIC_TOKEN" | buildkite-agent redactor add

# Now any log output containing the token value shows [REDACTED]
echo "Using token: $DYNAMIC_TOKEN"
# Output: Using token: [REDACTED]

複数の値

# Redact multiple values
echo "$SECRET1" | buildkite-agent redactor add
echo "$SECRET2" | buildkite-agent redactor add

レダクターと secret get の使い分け

シナリオ	使用するもの
Buildkite クラスターシークレットに保存されたシークレット	buildkite-agent secret get（自動的にレダクション）
外部のボールト（HashiCorp Vault、AWS SSM など）から取得するシークレット	外部から取得した後、buildkite-agent redactor add を実行
計算によって生成された機密値（一時トークン、派生キー）	buildkite-agent redactor add

ツールの署名

パイプライン YAML に署名すると、エージェントは実行前にステップの整合性を検証できます。tool sign コマンドは個々のステップではなく、パイプラインファイルを受け取り、署名を付与します。

ファイルからパイプラインに署名する

# Sign a pipeline YAML file using a local JWKS key
buildkite-agent tool sign pipeline.yml \
  --jwks-file /path/to/private-key.json \
  --repo "[email protected]:org/repo.git"

GraphQL API 経由で署名する

# Retrieve, sign, and update a pipeline via the Buildkite GraphQL API
buildkite-agent tool sign \
  --graphql-token "$BUILDKITE_GRAPHQL_TOKEN" \
  --organization-slug my-org \
  --pipeline-slug my-pipeline \
  --jwks-file /path/to/private-key.json \
  --update

署名キーペアを生成する

# Generate a new JWS key pair (private + public JWKS files)
buildkite-agent tool keygen

主なフラグ

コマンド	フラグ	説明
tool sign	--jwks-file	署名に使用する JWKS 秘密鍵ファイルのパス
tool sign	--jwks-key-id	JWKS ファイルから使用するキー ID
tool sign	--repo	リポジトリ URL（ファイルから署名する場合は必須）
tool sign	--signing-aws-kms-key	署名に使用する AWS KMS キー ID（JWKS の代替）
tool sign	--signing-gcp-kms-key	署名に使用する GCP KMS キー ID（JWKS の代替）
tool sign	--graphql-token	GraphQL API 経由でパイプラインを取得・更新するためのトークン
tool sign	--update	署名後に Buildkite のパイプラインを更新します（--graphql-token が必要）
tool keygen	--alg	JWS 署名アルゴリズム（デフォルト：EdDSA）
tool keygen	--key-id	生成するキーペアのキー ID（デフォルト：ランダム）

注： tool verify コマンドはありません。署名の検証は、エージェントがジョブを受け取る際に内部で行われます。

パイプライン署名の設定と段階的な導入戦略については、buildkite-secure-delivery スキルを参照してください。

よくある間違い

間違い	発生すること	対処方法
annotate で --context を指定しない	呼び出すたびに新しいアノテーションが作成され、既存のものが更新されません	常に、安定した識別子を指定して --context を渡してください
一致する --context を指定せずに --append を使用する	追加されず、新しいアノテーションが作成されます	--context が追加先のアノテーションと一致していることを確認してください
アーティファクトの glob パターンを引用符で囲み忘れる	buildkite-agent が処理する前にシェルが glob を展開します	常に "dist/**/*" のように引用符で囲んでください。dist/**/* のようにはしないでください
書き込みジョブの完了前に meta-data get を実行する	キーが存在せず、コマンドがゼロ以外の終了コードで失敗します	depends_on または wait を使って順序を保証するか、--default を使ってください
意図せず pipeline upload --replace を使用する	ビルド内の残りのすべてのステップが削除されます	パイプライン全体を意図的に再構築する場合にのみ --replace を使用してください
スクリプトの失敗時にロックを解放しない	ロックが無期限に保持され、ほかのジョブがブロックされます	trap ... EXIT を使って、どのような終了時にもロックを解放してください
OIDC プロバイダーの設定と一致しない --audience を渡す	トークンが対象のサービスに拒否されます	Audience は、プロバイダーに設定された audience URL と完全に一致する必要があります
実際のシークレットに --skip-redaction を使用する	シークレットの値がビルドログに平文で表示されます	--skip-redaction は、機密情報ではない設定値にのみ使用してください
現在のシェルに反映されることを期待して env set を呼び出す	変数は後続のフックやフェーズ向けに設定され、現在のスクリプトには反映されません	現在のスクリプト内の変数には export VAR=value を、フェーズをまたいで使用する場合は env set を使ってください
環境変数を介して大きな値を渡す	OS レベルの環境変数サイズ制限によって、通知されずに切り詰められたり、ジョブが失敗したりします	数 KB を超えるペイロードには、ファイルベースの方法（アーティファクト、ファイルを使ったメタデータ）に切り替えてください
--no-interpolation モードをオフにしたまま、エスケープされていない $ を含むパイプライン YAML をアップロードする	変数が予期せず展開され、YAML が不正な形式になります	YAML にリテラルの $ 文字が含まれる場合は --no-interpolation を使ってください

追加リソース

リファレンスファイル

• references/flag-reference.md — upload、download、search、shasum、annotate、meta-data、pipeline upload、oidc、step、lock、env、secret、redactor、tool を含む、すべてのサブコマンドのフラグ一覧
• references/patterns-and-recipes.md — 高度な複数サブコマンドのパターン：テスト失敗のアノテーションパイプライン、ジョブをまたぐステートマシン、OIDC 認証による Docker のプッシュ、ロックを使った並列ジョブの調整、環境のデバッグ

関連資料

• LLM 向け Buildkite ドキュメント
• Agent CLI — アノテーション
• Agent CLI — アーティファクト
• Agent CLI — メタデータ
• Agent CLI — パイプライン
• Agent CLI — OIDC
• Agent CLI — ロック
• Buildkite シークレットを使ったシークレットの管理
• 動的パイプライン