Bitbucket の CLI を使う

Bitbucket Cloud を接続しておくと、エージェントが bkt（Bitbucket CLI）でプルリクエストを作り、読み、コメントし、パイプラインの様子を見られます。セッションの中で bkt auth login をする必要はありません。

全体像

あなたがやること	エージェントがやること
Bitbucket を接続する	`bkt` を、ログインなしで使う
やってほしいことを頼む	あなたのアカウントとしてプルリクエストを作る・コメントする
権限が足りないと言われたら、接続を直す	権限が足りないときは、そう伝えて止まる

bkt は、呼び出しのたびに保存済みの接続を読みます。期限のあるトークンは、git と同じように使うときに更新されます。エージェントは最初から使い方を知っているので、コマンドを教える必要はありません。

始める前に

⚙設定 →「Git ホスティング」 で Bitbucket Cloud（bitbucket.org）を接続します。git の clone・push と同じ接続です。手順は Git のサービスを接続するにあります。

Bitbucket Data Center は、設定画面からは接続できません。自分で設定します
「アプリトークンで接続」 でつなぐときは、bkt で使う分のスコープもトークンに付けておきます（スコープ）

エージェントに頼む

ふだんどおりにお願いするだけです。

この変更でプルリクエストを作って。説明は日本語で

PR 123 のレビューコメントを読んで、直して push して

main のパイプラインが落ちている理由を調べて

エージェントは次のようなことができます。

やること	例
プルリクエストを作る	`bkt pr create`
プルリクエストを一覧する・読む	`bkt pr list`、`bkt pr view 123`
コメントを読む	`bkt pr comments 123`
パイプラインを見る	`bkt pipeline`

書き込みはあなたの名前で残ります。 できることは、あなたのアカウントと接続に許されている範囲までです
MCP サーバーより bkt を使います。 エージェントにはそう伝えてあります。CLI は呼び出しのたびに接続を読むので、ログインが切れてセッションを再起動する、ということがありません

スコープ

bkt は、接続に与えられた権限の範囲でしか動きません。接続そのものに要る権限（OAuth なら Account: Read と Repositories: Read/Write、API トークンなら read:account・read:workspace:bitbucket・read:repository:bitbucket）だけでは、プルリクエストやパイプラインは扱えません。

やること	OAuth で接続したとき	API トークンで接続したとき
プルリクエスト（作成・コメント）	Pull requests: Read and Write	`read:pullrequest:bitbucket`、`write:pullrequest:bitbucket`
パイプラインを見る	Pipelines: Read	`read:pipeline:bitbucket`
パイプラインを開始・停止する	Pipelines: Write	`write:pipeline:bitbucket`

OAuth の権限は、テナント管理者が Bitbucket の OAuth コンシューマーに設定します。足したあとは、Bitbucket をつなぎ直すと新しい権限になります
API トークンのスコープは、トークンを作るときに付けます。write は read を含みません。足りないときは、スコープを付けた新しいトークンを貼り直します
同じ権限で、課題管理の詳細から Bitbucket のプルリクエストに「作業の報告をコメントする」が使えます。このボタンは、接続がプルリクエストの書き込み権限を持つとわかっているときだけ出ます

自分の設定で使う

自分で設定したものがあれば、bkt はそちらを使います。

こうしているとき	動き
`bkt auth login` をした、または `BKT_HOST`・`BKT_TOKEN` を設定した	`bkt` はあなたの設定どおりに動き、接続は使いません

bkt の設定は、Data Center のホストだけのつもりでも bitbucket.org にも効きます。bitbucket.org で接続を使いたいときは、設定ファイル（~/.config/bkt/config.yml）を消してください

困ったとき

`bkt` が「lacks a scope for this command」と出す

接続に、そのコマンドの権限がありません。メッセージに、足りない権限の名前が出ます。

OAuth の接続：テナント管理者に権限を足してもらい、⚙設定 →「Git ホスティング」で Bitbucket をつなぎ直します
API トークンの接続：スコープを付けた新しいトークンを作って、貼り直します

別のトークンでやり直しても直りません。プルリクエストのスコープがないトークンでは、リポジトリの一覧は取れても bkt pr list が 403 Forbidden になります。

`bkt` がログインしていないと言う

接続がないか、使えなくなっています。⚙設定 →「Git ホスティング」で、Bitbucket のカードが「接続済み」かを見てください。

メールアドレスではないユーザー名（以前のアプリパスワード）で接続しているときは、git は動いても bkt は動きません。「アプリトークンで接続」でつなぎ直してください
自分の設定が残っていると、接続は使われません

「作業の報告をコメントする」が出ない

接続がプルリクエストの書き込み権限を持つと、まだわかっていません。スコープのとおり権限を足し、 Bitbucket をつなぎ直してください。Bitbucket の課題（issue）は一覧に出ないので、コメントできるのはプルリクエストだけです。