Bitbucket REST API 実践ガイド

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

Bitbucket REST API とは

Bitbucket REST API は、Bitbucket Cloud を自動化するために Atlassian が公開している HTTP インターフェイスです。リポジトリの作成、プルリクエストの作成とマージ、パイプラインの起動、ブランチ権限の管理、コミットの参照などを行えます。現在のバージョンは 2.0 で、すべてのエンドポイントは 1 つのベース URL https://api.bitbucket.org/2.0/ の下にあります。リクエストは通常の HTTPS 呼び出しで、レスポンスは JSON として返るため、認証付きの GET や POST を送れるものであれば、curl でも Python スクリプトでも CI ジョブでも Bitbucket を操作できます。

この API はいくつかの名詞を中心に構成されています。ワークスペースがリポジトリをまとめ、リポジトリはスラッグで識別され、プルリクエストやパイプラインといったリソースはリポジトリにぶら下がります。典型的なパスは左から右へ /2.0/repositories/{workspace}/{repo_slug}/pullrequests のように読めます。この形さえ分かれば、API の大部分は最後のセグメントを差し替えるだけでたどれます。

このガイドでは、認証、実際によく使うエンドポイント、ページネーションとレート制限の仕組み、そして毎回同じ curl と jq の配管を書かずに済ませるために API の前にコマンドラインラッパーを置く方法を解説します。

認証方式の選択肢

Bitbucket REST API へのリクエストは、すべて認証が必要です。Bitbucket Cloud は複数の方式に対応しており、その場かぎりのスクリプトなのか、長期間動かす自動化なのかによって選ぶ方式が変わります。

• アプリパスワード（HTTP Basic 認証）。アプリパスワードはアカウントに紐づくスコープ付きの認証情報で、Basic 認証のパスワードとして渡します。スクリプトにはもっとも手軽な方法で、curl -u "username:app_password" で使えます。
• アクセストークン。リポジトリ、プロジェクト、ワークスペースのアクセストークンは、アカウント全体ではなく単一のリソースにスコープされます。権限を狭く付与でき、パスワードを変更せずにトークンを失効させられるため、自動化では安全な既定の選択肢です。
• OAuth 2.0。他のユーザーの代理として動作するアプリケーションでは、OAuth コンシューマーを登録してベアラートークンと交換します。個人用のスクリプトではなく連携機能を作る場合は、こちらが適切です。

以下の例では、認証情報がシェルの履歴やコミットされたファイルに残らないよう、環境変数に格納します。

# Export a Basic-auth credential for the current shell session
export BB_USER="your-bitbucket-username"
export BB_APP_PASSWORD="your-app-password"

アクセストークンを使う場合は、ベアラートークンとして送ります。-H "Authorization: Bearer $BB_TOKEN" のように指定します。エンドポイントは同じで、変わるのは認証ヘッダーだけです。

主要な REST 2.0 エンドポイント

API 全体を覚える必要はありません。実際には、ごく少数のエンドポイントで自動化の大半をカバーできます。覚えておく価値のあるものは次のとおりです。いずれも https://api.bitbucket.org/2.0/ からの相対パスです。

curl でリクエストを送る

API を覚えるいちばん速い方法は、直接叩いてみることです。まずは認証情報が有効かどうかを確認し、JSON の形を見られる読み取りから始めます。

# List the first 10 repositories in a workspace
curl -s -u "$BB_USER:$BB_APP_PASSWORD" \
  "https://api.bitbucket.org/2.0/repositories/myteam?pagelen=10"

読み取りは気軽に試せます。API の真価が出るのは書き込みです。プルリクエストの作成は、ソースブランチと宛先ブランチを記述した小さな JSON ボディを添えた POST です。

# Open a pull request from feature/new into main
curl -s -u "$BB_USER:$BB_APP_PASSWORD" \
  -X POST \
  -H "Content-Type: application/json" \
  "https://api.bitbucket.org/2.0/repositories/myteam/api-service/pullrequests" \
  -d '{
    "title": "Add feature",
    "source": { "branch": { "name": "feature/new" } },
    "destination": { "branch": { "name": "main" } }
  }'

パイプラインの起動も同じパターンです。ボディでどの ref をビルドするかを Bitbucket に伝えます。

# Trigger the default pipeline on the main branch
curl -s -u "$BB_USER:$BB_APP_PASSWORD" \
  -X POST \
  -H "Content-Type: application/json" \
  "https://api.bitbucket.org/2.0/repositories/myteam/api-service/pipelines/" \
  -d '{
    "target": {
      "type": "pipeline_ref_target",
      "ref_type": "branch",
      "ref_name": "main"
    }
  }'

この 3 つのリクエスト（一覧表示、PR の作成、パイプラインの起動）は API 全体を代表するものです。他の操作もほとんどが同じ組み立ての変形で、ワークスペースとリポジトリから作ったパス、メソッド、JSON ボディという構成になります。面倒なのは周辺部分です。クエリパラメーターのエンコード、ページネーションの追跡、レスポンスごとの JSON の解析、そしてスロットリングされたときの再試行です。

ページネーションとレート制限

Bitbucket REST API を直接スクリプトから叩くとき、つまずきやすい挙動が 2 つあります。

ページネーション。コレクション系のエンドポイントは、すべての結果を一度に返しません。次のような形のページオブジェクトを返します。

{
  "pagelen": 10,
  "page": 1,
  "values": [ /* repositories, PRs, commits... */ ],
  "next": "https://api.bitbucket.org/2.0/repositories/myteam?page=2"
}

すべての結果を読むには、next のフィールドがなくなるまでその URL をたどります。pagelen クエリパラメーターで 1 ページあたりの件数を増やせば、往復回数を減らせます。最初のページしか読まないスクリプトは黙ってデータを取りこぼします。よくある、しかも気づきにくいバグです。

レート制限。Bitbucket は 1 時間あたりのレート制限を課しており、超えると HTTP 429 を返します。堅牢なクライアントはこのステータスを検知し、再試行の前にバックオフする必要があります。そうしないと大きなバッチ処理が途中から失敗し始めます。ページネーションとバックオフを正しく実装することが、良い Bitbucket クライアントを作る作業の大半であり、ラッパーが取り除いてくれるのはまさにこの定型処理です。

CLI で API をラップする

Bitbucket REST API を繰り返し使うなら、コマンドラインラッパーを挟むことで、先ほどの curl のブロックがそれぞれ 1 行になります。atlassian-cli は上記の REST 2.0 エンドポイントを短いコマンドに対応づけ、認証、ページネーション、429 のバックオフを内部で処理するため、配管を書かずに完全な結果を得られます。

一度認証しておけば、URL ではなく目的でコマンドを呼び出せます。設定の詳細は認証ガイドを参照してください。

# Store credentials in a named profile
atlassian-cli auth login \
  --profile work \
  --base-url https://your-workspace.atlassian.net \
  --email you@example.com \
  --token $TOKEN \
  --default

# Confirm the Bitbucket credential resolves
atlassian-cli bitbucket whoami

そこから先は、手で書いていた操作がすべて 1 行になります。リポジトリの一覧表示では、すべてのページを自動でたどります。

# List repositories in a workspace (pagination handled automatically)
atlassian-cli bitbucket --workspace myteam repo list --limit 10

# Machine-readable output for scripting
atlassian-cli bitbucket --workspace myteam repo list --format json | jq '.[].slug'

プルリクエストの作成に、手で組み立てた JSON ボディは不要になります。

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

# Approve and merge it
atlassian-cli bitbucket --workspace myteam pr approve api-service 123
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 --strategy merge_commit

パイプラインの起動は、先ほどの POST が引数にまとまります。bitbucket-pipelines.yml に定義した名前付きカスタムパイプラインにも対応しています。

# Trigger the 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

どのコマンドもグローバルな --format json|csv|yaml フラグを受け付けるため、生の HTTP レスポンスを解析せずに結果を jq や表計算ソフト、他のツールへ渡せます。入力を短くしたい場合は、bb エイリアスを bitbucket の代わりに使えます。

エンドポイントと CLI コマンドの対応

必要な REST エンドポイントがすでに分かっている場合は、この表で対応する atlassian-cli のコマンドを確認できます。既存の curl スクリプトを CLI へ移行するときの橋渡しになります。全一覧はコマンドリファレンスにあります。

これらのコマンドを組み合わせた繰り返し実行できるワークフローについては、Bitbucket PR 自動化ランブックにレビューからマージまでの完全なスクリプトがあり、Bitbucket CLI ガイドでは日常的な使い方をより詳しく解説しています。関連記事の CLI から Bitbucket API を呼び出すと Bitbucket CLI コマンド一覧では、それぞれの領域をさらに掘り下げています。

よくある質問

関連リソース