CLI から Bitbucket Pipelines を起動して監視する

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。製品名は互換性を示す目的でのみ使用しています。

コマンドラインから Bitbucket Pipelines を起動して監視するには、atlassian-cli に組み込まれた bitbucket pipelines cli を使います。atlassian-cli bitbucket pipeline trigger --ref-name main でビルドを開始し、pipeline watch または pipeline status --wait で完了まで追跡します。ダッシュボードも、手作業のクリックも、ブラウザのタブを見張る必要もありません。

この記事では運用者のワークフローに絞って解説します。実行の開始（bitbucket-pipelines.yml の名前付きカスタムパイプラインを含む）、ターミナルでのログ確認、そしてプロセスの終了コードを通じた結果のスクリプト連携です。以下のコマンドはすべてそのままコピーして使え、バイナリが実際に備えるサブコマンドと一致しています。

acli との違い: atlassian-cli はコミュニティによる独立した MIT ライセンスのオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。ベンダーによる一次サポートが必要な場合は acli を使ってください。Jira、Confluence、Bitbucket、Jira Service Management を横断し、パイプライン操作まで含んだ無料の単一 Rust バイナリが欲しい場合は atlassian-cli を使ってください。

Bitbucket Pipelines CLI の仕組み

パイプライン関連のコマンドは atlassian-cli bitbucket pipeline の下にあります（短い bb エイリアスもどこでも使えます）。各コマンドはワークスペースとリポジトリの 2 つを知る必要があります。次のように明示的に指定できます。

# Explicit workspace and repo
atlassian-cli bitbucket --workspace myteam --repo api-service \
  pipeline list

どちらも省略できます。クローン済みのリポジトリ内で実行すると、--repo は git のリモートから自動検出され、ワークスペースは設定済みのプロファイルから解決されます。プロジェクトのディレクトリからなら、同じコマンドは次のように短くなります。

# Inside a cloned Bitbucket repo, both are inferred
cd api-service
atlassian-cli bb pipeline list --recent 5

その前に認証が必要です。まだプロファイルを作成していない場合は atlassian-cli auth login を一度実行し、認証ガイドに従ってください。以下の例では曖昧さを避けるため --workspace/--repo を明示していますが、リポジトリ内にいるときはこれらのフラグを省略できます。

パイプラインを起動する

中心となるコマンドは pipeline trigger です。必須のフラグは --ref-name だけで、ビルド対象のブランチまたはタグを指定します。

# Run the default branch pipeline on main
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline trigger --ref-name main

既定では ref はブランチとして扱われます。タグをビルドする場合は --ref-type tag を追加します。

# Build a release tag
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline trigger --ref-name v1.4.0 --ref-type tag

--var KEY=VALUE フラグを繰り返し指定すると、実行に変数を渡せます。通常は Bitbucket の UI で設定する変数と同じように動作しますが、スコープはこの 1 回の実行だけです。--secured を追加するとすべてシークレットとして扱われ、ログ上でマスクされます。

# Pass build-time variables into a single run
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline trigger --ref-name main \
  --var DEPLOY_ENV=staging \
  --var RELEASE_NOTES="hotfix 1.4.1"

trigger は必ず新しいビルド番号を返します。この番号（またはパイプラインの UUID）が、watch、logs、get、stop に渡すハンドルになります。

カスタムパイプラインを実行する

Bitbucket では bitbucket-pipelines.yml の custom: セクションに名前付きパイプラインを定義できます。これらは push では自動実行されず、必要なときに手動で呼び出すためのものです。夜間の統合テスト、1 回限りのデータ移行、手動のデプロイゲートなどが典型例です。--custom-pipeline フラグは、そのうちのひとつを名前で指定して実行します。

# bitbucket-pipelines.yml
# pipelines:
#   custom:
#     s3-access-test:
#       - step:
#           script:
#             - ./scripts/check-s3.sh

# Trigger that custom pipeline against main
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline trigger --ref-name main \
  --custom-pipeline s3-access-test

--custom-pipeline の後に続くセレクター名は、custom: 配下のキーと完全に一致している必要があります。通常の trigger と同じように --var や --secured と組み合わせられるので、YAML を編集せずに手動デプロイをパラメーター化できます。

# Manual deploy pipeline, parameterized per run
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline trigger --ref-name main \
  --custom-pipeline deploy \
  --var TARGET=production --secured

実行が終わるまで監視する

ビルドを起動しただけでは仕事の半分です。pipeline watch は実行をポーリングし、最終結果に達するまで状態を出力してから終了します。引数なしでは直近のパイプラインを追跡し、ビルド番号を渡すと特定の実行を追跡します。

# Watch the latest run, refreshing every 10 seconds, with per-step status
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline watch --interval 10 --steps

ポーリング間隔の既定値は 5 秒です。無人環境で watch を使うときに役立つフラグがいくつかあります。

• --timeout <seconds> は待機時間の上限を決めます。時間内に実行が終わらない場合、コマンドは終了コード 2 で終了するため、停止したビルドを失敗として扱えます。
• --on-complete <command> はパイプラインが完了した瞬間にシェルコマンドを実行します。環境変数 PIPELINE_STATUS、PIPELINE_BUILD_NUMBER、PIPELINE_UUID、PIPELINE_REF_NAME が渡されます。
• --log は ANSI エスケープコードなしで、ポーリング 1 回につき 1 行を出力します。出力をファイルに保存する場合に適しています。標準出力がターミナルでない場合は自動的に有効になります。

# Watch build 412, notify on completion, give up after 30 minutes
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline watch 412 \
  --timeout 1800 \
  --on-complete 'echo "Build #$PIPELINE_BUILD_NUMBER finished: $PIPELINE_STATUS"'

--on-complete にはステータスとビルド番号が環境変数として渡されるため、Slack への通知、デスクトップ通知、後続処理の起動などのフックとして自然に使えます。

ログの表示とフィルタリング

ビルドが壊れたときに見たいのはブラウザのタブではなくログです。pipeline logs は実行の各ステップの出力をターミナルに直接表示します。位置引数がなければ最新のパイプラインが対象になり、ビルド番号を渡すと特定の実行を選べます。

# Print logs for the latest run
atlassian-cli bb --workspace myteam --repo api-service pipeline logs

# Logs for a specific build
atlassian-cli bb --workspace myteam --repo api-service pipeline logs 412

複数ステップのビルドではログがすぐに長くなるため、絞り込むためのフラグが用意されています。--failed-only は成功したステップを飛ばし、--step は名前でステップを指定し、--grep はログ行を絞り込みます（大文字小文字を区別しない場合は -i を追加します）。

# Only the failed steps of a broken build
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline logs 412 --failed-only

# Just the error lines, case-insensitive
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline logs 412 --grep "error" -i

# Logs from a single named step
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline logs 412 --step "Run tests"

--failed-only と --grep を組み合わせるのが、「直近のビルドはなぜ失敗したのか」に最速で答える方法です。成功したステップのノイズをスクロールする必要はありません。

CI 向けのステータスと終了コード

パイプラインのコマンドをスクリプトに組み込みやすいのは、パイプラインの状態を意味のあるプロセス終了コードに対応付けているからです。pipeline status は最新の実行を JSON で出力し、分岐に使える終了コードを返します。

--wait を追加すると、指定した --interval（既定は 10 秒）でポーリングしながら、実行が最終状態に達するまで待ってから戻ります。これにより、ビルドの完了を待ち、その結果を $? で伝える 1 つのコマンドになります。

# Wait for the latest run, then act on the result
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline status --wait --interval 15

if [ $? -eq 0 ]; then
  echo "Pipeline green, promoting build"
else
  echo "Pipeline not green, aborting" >&2
  exit 1
fi

終了コードが本物なので、if はほとんど不要です。set -e のもとでは、ゼロ以外のステータスがそれだけでスクリプトを止めます。また status は JSON を出力するので、終了コード以上の情報が必要なときは jq で特定のフィールドを取り出せます。

# Extract the build number of the latest run
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline status --format json | jq '.build_number'

失敗したビルドの調査と再実行

起動と監視に加えて、CLI は調査と再試行のループもカバーします。pipeline list は最近の実行を一覧表示し、pipeline latest はブランチの最新の実行に直接ジャンプし、pipeline get は 1 件の実行を詳細に表示します。いずれにも --steps を追加すると、ステップごとのステータスが含まれます。

# Five most recent runs with step summaries
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline list --recent 5 --steps

# Latest run on a specific branch
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline latest --branch main --steps

# Full detail of one run by build number
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline get 412 --steps

pipeline list は --branch による絞り込み、--since と --before による期間指定（24h、7d、ISO 形式のタイムスタンプなどを受け付けます）、--pr によるプルリクエスト単位の絞り込みにも対応します。不安定な実行をもう一度試したいときは、pipeline rerun が同じコミットで再実行します。

# Re-run a specific build on the same commit
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline rerun 412

# Re-run only the failed steps of a PR's latest pipeline
atlassian-cli bb --workspace myteam --repo api-service \
  pipeline rerun --pr 128 --failed-only

進展のない実行を中止するには、pipeline stop に同じビルド番号または UUID のハンドルを渡します。

atlassian-cli bb --workspace myteam --repo api-service \
  pipeline stop 412

コマンドリファレンス

パイプラインのサブコマンドと、よく使うフラグの一覧です。

Bitbucket のすべてのコマンドのフラグ一覧はコマンドリファレンスを、リポジトリ、ブランチ、プルリクエスト、権限を含む幅広い Bitbucket のワークフローは Bitbucket CLI ハブをご覧ください。

よくある質問

関連リソース