コマンドラインから Bitbucket API を使う

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

Bitbucket API をタスク起点で使う

ターミナルから Bitbucket API を操作するのに、curl リクエストを 1 つも書く必要はありません。URL を組み立て、Authorization ヘッダーを付け、page リンクを辿り、JSON を手で解析する代わりに、bitbucket pr list や bitbucket pipeline trigger のような名前付きコマンドを実行すれば、指定した形式で結果が返ってきます。

この記事は意図的にタスク起点です。Bitbucket の REST エンドポイントをフィールド単位で網羅するリファレンスではありません。リポジトリの一覧、プルリクエストの作成とマージ、パイプラインの起動、権限の監査といった、エンジニアが実際に行う操作を辿り、それぞれに対応する atlassian-cli のコマンドを示します。以下のコマンドはすべてコピーして実行でき、コマンドリファレンスと突き合わせて確認しています。

内部では、atlassian-cli も手動で叩くのと同じ Bitbucket Cloud の REST API と通信しています。違いは、ページネーション、認証、レート制限時のバックオフ、出力の整形がすでに処理されている点です。つまり、シェルの 1 行が小さなスクリプトの代わりになり、同じコマンドが対話的にも CI の中でも動きます。

一度だけ認証する

Bitbucket Cloud は Jira や Confluence とは別に認証するため、ログイン時に --bitbucket フラグを渡します。トークンのフローは 2 種類あります。アカウントに合うほうを選んでください。

API トークン（Basic 認証）

Bitbucket にスコープを絞った Atlassian の API トークンを作成し、アカウントのメールアドレスとあわせて使います。個人アカウント向けです。

# Log in with an API token (Basic auth)
atlassian-cli auth login \
  --profile work \
  --bitbucket \
  --email you@company.com \
  --token $BITBUCKET_TOKEN

アクセストークン（Bearer 認証）

アクセストークンはリポジトリ、プロジェクト、ワークスペースにスコープを絞れるため、最小権限で動かしたい CI に向いています。Bearer 認証では --email は不要です。

# Log in with a scoped access token (Bearer auth)
atlassian-cli auth login \
  --profile bb-ci \
  --bitbucket --bearer \
  --token $BITBUCKET_TOKEN

# Confirm the credentials resolve
atlassian-cli auth test --bitbucket --profile bb-ci
atlassian-cli bitbucket whoami --profile bb-ci

覚えておくと便利な点として、bb は bitbucket のエイリアスなので、atlassian-cli bb whoami と atlassian-cli bitbucket whoami は同じです。以下の例はどちらの書き方でも動きます。

リポジトリ、ブランチ、コミットを読む

Bitbucket API を使う作業の多くは、状態の読み取りから始まります。ワークスペースのスラッグは --workspace で指定するか、ログイン時にプロファイルへ保存します。リポジトリのスラッグは位置引数です。まずはワークスペース内のリポジトリからです。

# List repositories in a workspace
atlassian-cli bitbucket --workspace myteam repo list --limit 10

# Get one repository's details
atlassian-cli bitbucket --workspace myteam repo get api-service

どのコマンドにも --format json（または -f json）を付けて jq にパイプできます。CLI が背後の API をページ送りしてくれるため、JSON にはすでに全件が含まれています。最初の 1 ページだけを見ているわけではありません。

# Every repo slug in the workspace, one per line
atlassian-cli bitbucket --workspace myteam repo list \
  --format json | jq '.[].slug'

# List branches, then recent commits on main
atlassian-cli bitbucket --workspace myteam branch list api-service
atlassian-cli bitbucket --workspace myteam commit list api-service --branch main

コミットの調査は、リリースノートや監査に役立ちます。単一のコミットの差分を見たり、指定した ref のパスを辿ったりできます。

# Show the diff for a commit
atlassian-cli bitbucket --workspace myteam commit diff api-service abc123

# Browse a directory at a ref
atlassian-cli bitbucket --workspace myteam commit browse api-service --commit main --path src/

出力は要求に応じて JSON、CSV、YAML になるだけなので、これらのコマンドはすでに使っている仕組みにそのまま組み込めます。JSON を jq にパイプする、表計算用に CSV をファイルへ直接書き出す、CI では --format quiet で終了コードによる判定に使う、といった使い方ができます。

プルリクエストの操作

Bitbucket API を CLI で扱う価値が最も出るのはプルリクエストです。レビューのサイクルが、小さな API 呼び出しの連続だからです。リポジトリのオープンな PR を一覧し、数値の ID を指定して操作します。

# Open pull requests on a repo
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --limit 5

# Full detail for PR #123
atlassian-cli bitbucket --workspace myteam pr get api-service 123

プルリクエストの作成はコマンド 1 つです。タイトル、ソースブランチ、宛先ブランチを指定します。

# Open a PR from a feature branch into main
atlassian-cli bitbucket --workspace myteam pr create api-service \
  --title "Add rate limiter" \
  --source feature/rate-limiter \
  --destination main

レビュー、コメント、承認、マージも、それぞれコマンド 1 つです。マージ戦略は明示的に指定するため、スクリプトが推測することはありません。

# Leave a review comment
atlassian-cli bitbucket --workspace myteam pr comment api-service 123 \
  --text "Looks good, one nit on error handling."

# Approve, then merge with a merge commit
atlassian-cli bitbucket --workspace myteam pr approve api-service 123
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 --strategy merge_commit

一覧と --format json を組み合わせれば、軽量なレビュー用ダッシュボードを作れます。たとえば Web の UI に触れずに、リポジトリごとのオープンな PR 数を数えたり、長く開いたままの PR を探したりできます。

# IDs of every open PR on a repo
atlassian-cli bitbucket --workspace myteam pr list api-service \
  --state OPEN --format json | jq '.[].id'

PR を絞り込み、承認状況を確認し、条件を満たしたものをマージする、マージキュー方式のスクリプト全体はBitbucket PR 自動化のランブックを参照してください。

パイプラインと CI の起動

Bitbucket API は Pipelines の実行を開始できます。つまり、ターミナルが届く場所ならどこからでも CI をスクリプトで動かせます。ブランチを指定して実行するか、bitbucket-pipelines.yml で定義した名前付きのカスタムパイプラインを実行します。

# Trigger the default pipeline on main
atlassian-cli bitbucket --workspace myteam pipeline trigger api-service --ref-name main

# Trigger a named custom pipeline
atlassian-cli bitbucket --workspace myteam pipeline trigger api-service \
  --ref-name main --custom-pipeline s3-access-test

最近の実行を一覧してステータスを確認し、間違って起動した場合は UUID を指定して停止できます。

# See recent pipeline runs
atlassian-cli bitbucket --workspace myteam pipeline list api-service

# Stop a running pipeline
atlassian-cli bitbucket --workspace myteam pipeline stop api-service {uuid}

これは処理をつなぐときに便利です。デプロイスクリプトからパイプラインを起動したり、定期ジョブから固定の ref に対して夜間のカスタムパイプラインを起動したりできます。CLI は構造化された出力を返すため、JSON から実行の識別子を取り出して、その後の処理をプログラムから続けられます。

権限、Webhook、監査

管理系の作業も、そのままコマンドに対応します。リポジトリへのアクセス権を確認し、権限を付与し、Bitbucket をほかのツールチェーンにつなぐ Webhook や SSH キーを管理できます。

# Who can access this repo, and at what level
atlassian-cli bitbucket --workspace myteam permission list api-service

# Grant write access to a user
atlassian-cli bitbucket --workspace myteam permission grant api-service \
  --user-uuid {uuid} --permission write

# Manage webhooks
atlassian-cli bitbucket --workspace myteam webhook list api-service
atlassian-cli bitbucket --workspace myteam webhook create api-service \
  --url https://example.com/hook --events repo:push

ブランチ保護はよくあるガバナンス要件です。main へのマージを制限し、承認を必須にするのもコマンド 1 つです。

# Require 2 approvals and restrict merges on main
atlassian-cli bitbucket --workspace myteam branch protect api-service \
  --pattern "main" --kind restrict_merges --approvals 2

# Review existing restrictions
atlassian-cli bitbucket --workspace myteam branch restrictions api-service

ワークスペース全体の整理には一括コマンドがあり、それぞれ --dry-run フラグで、何かが変わる前に影響範囲を確認できます。

# Preview which repos would be archived (untouched by --dry-run)
atlassian-cli bitbucket --workspace myteam bulk archive-repos --days 180 --dry-run

# Preview stale branch cleanup, keeping one branch
atlassian-cli bitbucket --workspace myteam bulk delete-branches api-service \
  --exclude feature/keep --dry-run

権限とブランチのデータを共有できるインベントリにまとめる方法は、リポジトリ監査のランブックがワークスペース全体でのエクスポート手順を解説しています。

CLI と生の REST の比較

Bitbucket の REST API を curl で直接叩くことに問題はありません。CLI がラップしていないエンドポイントへの単発の呼び出しなら、それが適切な道具です。トレードオフが出るのは、その作業が繰り返しになったり、ページネーション、認証処理、解析が必要になったりした瞬間です。同じ作業を両方のやり方で並べると次のようになります。

目安としては、作業が繰り返しになる場合、CI で動かす必要がある場合、あるいは小さなスクリプトになりそうな場合は CLI を選びます。CLI がまだカバーしていないエンドポイントが必要なときは生の REST を選びます。両者は共存できます。CLI の JSON 出力は、curl 用にすでに書いた jq のフィルターにそのまま流せます。これらのコマンドの背後にあるエンドポイントの詳細は、Bitbucket REST API ガイドが生の HTTP の面を、Bitbucket CLI コマンドリファレンスがすべてのサブコマンドを扱っています。

よくある質問

関連リソース