Bitbucket CLI で PR、パイプライン、リポジトリを自動化

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

# Install
brew install omar16100/atlassian-cli/atlassian-cli

# List open pull requests
atlassian-cli bitbucket pr list --workspace myteam --repo api-service --state OPEN

なぜ CLI から Bitbucket を自動化するのか

Bitbucket の Web UI は、プルリクエストを 1 件レビューするだけなら十分に使えます。しかし、200 個のリポジトリの権限を監査したり、CI スクリプトからパイプラインを起動したり、ワークスペース全体の古いブランチを整理したりする用途には向いていません。

Bitbucket CLI を使うと、こうした何度もクリックする作業が 1 つのコマンドになります。atlassian-cli なら、Jira、Confluence、JSM を扱うのと同じバイナリで Bitbucket も一通りカバーできます。つまり、Atlassian のスタック全体を 1 つのツール、1 つの設定、1 つの認証フローで扱えます。コマンドの全一覧は Bitbucket CLI のドキュメントを参照してください。

Bitbucket のコマンドラインツールでよくある用途は次のとおりです。

• PR の自動化。スクリプトからプルリクエストを作成、承認、マージできます。PR の作成と Jira 課題の遷移を 1 つのパイプラインでつなげられます。
• パイプラインの起動。CI/CD システムから Bitbucket Pipelines を開始し、完了を監視して結果に応じた処理を行えます。ブラウザは不要です。
• リポジトリの監査。ワークスペース内の全リポジトリを一覧表示し、権限を確認し、使われていないリポジトリを洗い出し、命名規則をプログラムから適用できます。
• ブランチの整理。重要なブランチを保護し、マージ済みブランチを一括削除し、複数のリポジトリで承認要件を適用できます。

atlassian-cli は、すべての Bitbucket コマンドで bb という短縮エイリアスに対応しています。atlassian-cli bitbucket と atlassian-cli bb はどちらも同じ動作になります。

認証

Bitbucket では、Jira や Confluence とは別のスコープ付き API トークンが必要です。Atlassian は Bitbucket のアプリパスワードを非推奨とし、Bitbucket 専用に明示的な権限スコープを指定して作成するスコープ付き API トークンへ移行しました。

Basic 認証（API トークン）

スコープ付きの Bitbucket トークンは id.atlassian.com で作成します。「Create API token with scopes」をクリックして Bitbucket を選び、必要なスコープ（read:repository:bitbucket、write:repository:bitbucket、read:pullrequest:bitbucket）を追加してください。

# Set the Bitbucket token (profile-specific)
export ATLASSIAN_CLI_BITBUCKET_TOKEN_WORK=your-bitbucket-scoped-token

# Or use the generic fallback
export BITBUCKET_TOKEN=your-bitbucket-scoped-token

# Verify authentication
atlassian-cli bitbucket whoami

Bearer トークン認証

CI/CD パイプラインやサービスアカウントでは、Bearer トークン認証を使うとメールアドレスを露出せずに済みます。Bearer 用のプロファイルは次のように設定します。

# Add a Bitbucket Bearer token profile
atlassian-cli auth login \
  --profile bb-ci \
  --bitbucket --bearer \
  --workspace myteam

# Test the connection
atlassian-cli auth test --bitbucket --profile bb-ci

# Use the profile in commands
atlassian-cli bb --workspace myteam repo list --profile bb-ci

CLI は環境変数を優先順に確認します。まず ATLASSIAN_CLI_BITBUCKET_TOKEN_{PROFILE}、次に ATLASSIAN_BITBUCKET_TOKEN、その次に BITBUCKET_TOKEN を見て、最後に通常の ATLASSIAN_CLI_TOKEN_{PROFILE} トークンにフォールバックします。

リポジトリ管理

リポジトリの操作は、ワークスペース内でのリポジトリの一覧表示、作成、参照、更新、削除というライフサイクル全体をカバーします。

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

# Get details for a specific repo
atlassian-cli bitbucket --workspace myteam repo get api-service

# Create a new private repository
atlassian-cli bitbucket --workspace myteam repo create newrepo \
  --name "New Repo" --private

# Update a repo description
atlassian-cli bitbucket --workspace myteam repo update api-service \
  --description "Updated description"

# Delete a repo (requires --force)
atlassian-cli bitbucket --workspace myteam repo delete oldrepo --force

権限

リポジトリに誰がアクセスできるかを監査し、管理します。

# List permissions for a repository
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

ワークスペースとプロジェクト

# List workspaces you have access to
atlassian-cli bitbucket workspace list --limit 10

# Get workspace details
atlassian-cli bitbucket workspace get myteam

# List projects in a workspace
atlassian-cli bitbucket --workspace myteam project list

# Create a new project
atlassian-cli bitbucket --workspace myteam project create PROJ \
  --name "My Project" --private

プルリクエストのワークフロー

プルリクエスト関連のコマンドは、作成からレビュー、マージまで PR のライフサイクル全体をカバーします。日々の開発で Bitbucket CLI がもっとも時間を節約してくれる領域です。

PR の作成と一覧表示

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

# List open pull requests
atlassian-cli bitbucket --workspace myteam pr list api-service \
  --state OPEN --limit 5

# Get PR details
atlassian-cli bitbucket --workspace myteam pr get api-service 123

レビューとマージ

# Approve a PR
atlassian-cli bitbucket --workspace myteam pr approve api-service 123

# Merge with squash strategy
atlassian-cli bitbucket --workspace myteam pr merge api-service 123 \
  --strategy squash

# Decline a PR
atlassian-cli bitbucket --workspace myteam pr decline api-service 123

# Add a comment to a PR
atlassian-cli bitbucket --workspace myteam pr comment api-service 123 \
  --text "Looks good!"

# View PR comments
atlassian-cli bitbucket --workspace myteam pr comments api-service 123

マージ時の --strategy フラグは merge_commit、squash、fast_forward に対応しており、Bitbucket のマージ戦略と一致します。pr approve コマンドと組み合わせれば、レビューからマージまでの一連のワークフローをシェルスクリプトで組み立てられます。

パイプラインの操作

ターミナルから直接 Bitbucket Pipelines を起動、監視、管理できます。ビルドをプログラムから開始し、その結果に応じて処理を分ける CI/CD の自動化では欠かせません。

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

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

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

パイプライン関連のコマンドは PR のワークフローと相性がよく、たとえば PR を作成した後にパイプラインを起動し、完了を待って、ビルドが通ったら自動でマージする、という流れを 1 つのスクリプトにまとめられます。

Webhook と SSH キー

リポジトリ連携のための Webhook とデプロイキーの管理を自動化します。

# List webhooks
atlassian-cli bitbucket --workspace myteam webhook list api-service

# Create a webhook for push events
atlassian-cli bitbucket --workspace myteam webhook create api-service \
  --url https://example.com/hook \
  --events repo:push

# Manage SSH deploy keys
atlassian-cli bitbucket --workspace myteam ssh-key list api-service
atlassian-cli bitbucket --workspace myteam ssh-key add api-service \
  --label deploy --key "ssh-rsa ..."

ブランチ管理

ブランチ関連のコマンドは、一覧表示、作成、削除、保護ルールを扱います。ブランチ保護は、複数のリポジトリでコードレビューのポリシーを徹底するうえで特に重要です。

ブランチの一覧表示と作成

# List branches in a repository
atlassian-cli bitbucket --workspace myteam branch list api-service

# Create a feature branch from main
atlassian-cli bitbucket --workspace myteam branch create api-service \
  feature/new --from main

# Delete a merged branch
atlassian-cli bitbucket --workspace myteam branch delete api-service \
  feature/old --force

ブランチ保護

レビュー要件を強制し、重要なブランチにプッシュできる相手を制限します。

# Protect the main branch with 2 required approvals
atlassian-cli bitbucket --workspace myteam branch protect api-service \
  --pattern "main" \
  --kind restrict_merges \
  --approvals 2

# View branch restrictions
atlassian-cli bitbucket --workspace myteam branch restrictions api-service

ブランチの一括整理

複数のリポジトリにまたがる古いブランチを削除します。--dry-run フラグを付けると、実行前に削除対象を確認できます。

# Preview: list branches that would be deleted
atlassian-cli bitbucket --workspace myteam bulk delete-branches api-service \
  --exclude feature/keep \
  --dry-run

# Archive stale repos (no commits in 180 days)
atlassian-cli bitbucket --workspace myteam bulk archive-repos \
  --days 180 \
  --dry-run

実践的なワークフロー

CI/CD パイプラインの自動化

GitHub Actions、GitLab CI、その他の CI ランナーで Bitbucket CLI のコマンドを使い、ビルドパイプラインと Bitbucket の操作をつなげます。

#!/bin/bash
# Automated PR workflow: create, trigger pipeline, merge on success
set -euo pipefail

WORKSPACE="myteam"
REPO="api-service"
BRANCH="feature/automated-update"

# Create the pull request
PR_OUTPUT=$(atlassian-cli bb --workspace "$WORKSPACE" pr create "$REPO" \
  --title "Automated dependency update" \
  --source "$BRANCH" \
  --destination main \
  --format json)

# Trigger a pipeline on the branch
atlassian-cli bb --workspace "$WORKSPACE" pipeline trigger "$REPO" \
  --ref-name "$BRANCH"

echo "PR created and pipeline triggered."

リポジトリ監査スクリプト

ワークスペース内のすべてのリポジトリについて、権限、ブランチ保護、活動状況を監査します。

#!/bin/bash
# Audit all repos: check permissions and branch protection
set -euo pipefail

WORKSPACE="myteam"

# List all repos as JSON
REPOS=$(atlassian-cli bb --workspace "$WORKSPACE" repo list \
  --format json --limit 100)

# For each repo, check branch restrictions
echo "$REPOS" | jq -r '.[].slug' | while read -r repo; do
  echo "--- $repo ---"

  # Check permissions
  atlassian-cli bb --workspace "$WORKSPACE" permission list "$repo"

  # Check branch protection
  atlassian-cli bb --workspace "$WORKSPACE" branch restrictions "$repo"

  echo ""
done

コミットと差分の操作

リポジトリをクローンせずにコミット履歴と差分を確認します。

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

# View a commit diff
atlassian-cli bitbucket --workspace myteam commit diff api-service abc123

# Browse files at a specific commit
atlassian-cli bitbucket --workspace myteam commit browse api-service \
  --commit main --path src/

よくある質問

関連リソース