Jira、Confluence、Bitbucket をまたぐ Atlassian REST API

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

Atlassian REST API は実質 4 つの API

「これぞ Atlassian REST API」というものを探したことがあるなら、そんなものは存在しないと気づいたはずです。Atlassian は統一された単一の API を提供していません。Jira Cloud、Confluence Cloud、Bitbucket Cloud はそれぞれ独自の REST API を、別のベース URL、別のクエリ言語、別のページネーションモデルで公開しています。Jira Service Management は、Jira サイトの上に 4 つ目の面を重ねます。つまり、3 製品すべてに触れるスクリプトは、3 つの方言を同時に話す必要があります。

どれも単体では難しくありません。摩擦が生まれるのは、その継ぎ目です。Jira と Confluence では 1 つの方法で認証し、Bitbucket では別の方法で認証します。結果のページ送りも製品ごとに異なります。課題には JQL を、ページには CQL を覚えることになります。全体像は次のとおりです。

Jira にはボードとスプリント向けに /rest/agile/1.0 という別の Agile API もあり、Confluence は v2 と並行して /wiki/rest/api の古い v1 エンドポイントも提供し続けています。重要なのは、すべてのパスを暗記することではありません。「Atlassian API を呼ぶ」という作業が 1 つではなく 4 つあるということです。

1 つのバイナリ、1 つのコマンドの形

CLI のラッパーは、この 4 つの面を 1 つにまとめます。atlassian-cli は単一の Rust バイナリで、すべての製品を同じコマンドの形に対応づけます。atlassian-cli <product> <target> <verb> [flags] という形です。このパターンを一度覚えれば、Jira の課題を検索するときも、Confluence のページを一覧するときも、Bitbucket のプルリクエストをレビューするときも同じように使えます。

# Same verb, three different APIs, one consistent surface
atlassian-cli jira issue search --jql "project = DEV" --limit 5
atlassian-cli confluence page list --space DEV --limit 5
atlassian-cli bitbucket --workspace myteam repo list --limit 5

すべてのコマンドが同じグローバルフラグを受け付けます。--format <table|json|csv|yaml|quiet|markdown>、認証プロファイルを選ぶ --profile <name>、そして後段での解析を楽にするためにリスト出力を {"data": [...], "count": N} で包む --envelope です。この統一感こそが価値です。Jira の検索と Bitbucket の一覧から出てくる JSON は、同じ jq のパイプラインに流せます。

認証: トークン方式は 1 つでは足りない

「4 つの API」という現実が最初に効いてくるのは認証情報です。Jira、Confluence、Jira Service Management はいずれも同じ Atlassian Cloud サイト上にあるため、受け付けるものは同じです。アカウントのメールアドレスと API トークンを HTTP Basic 認証で送ります。Bitbucket Cloud は独自の認証情報モデルを持つ別製品で、以前はアプリパスワード、現在はアプリ単位でスコープを絞ったアクセストークンです。そのため、素のスクリプトは 2 つのホストに対して 2 種類のヘッダーを使い分けることになります。

atlassian-cli は、その両方をプロファイルにまとめます。一度認証すれば、各コマンドが製品ごとに適切な認証情報を再利用します。

# Store an Atlassian Cloud site profile (Jira / Confluence / JSM)
atlassian-cli auth login \
  --profile work \
  --base-url https://your-site.atlassian.net \
  --email you@example.com \
  --token "$ATLASSIAN_API_TOKEN" \
  --default

# Confirm the profile resolves and the token is valid
atlassian-cli auth whoami --profile work
atlassian-cli auth test --profile work

Bitbucket の認証情報もプロファイル単位で保存されます。そのため auth logout --bitbucket は、Atlassian Cloud のトークンを残したまま Bitbucket のトークンだけを削除できます。そもそもどの種類の認証情報を発行すべきか迷っている場合、API トークンとパーソナルアクセストークンのトレードオフは Atlassian の API トークンと PAT の違いで解説しています。手順全体は認証ガイドにあります。

クエリ言語: JQL、CQL、クエリパラメーター

検索は、3 製品の違いが最も大きく出るところです。Jira は JQL で課題を絞り込みます。Confluence は CQL でページ、ブログ記事、添付ファイルを絞り込みます。CQL は JQL に近い言語ですが、対象となるオブジェクトとフィールドが異なります。Bitbucket にはクエリ言語がまったくなく、リポジトリやプルリクエストは通常のクエリパラメーターで絞り込みます。atlassian-cli はそれぞれを適切な場所に対応づけているため、HTTP の形を意識して変換することなく、jira コマンドには JQL を、confluence コマンドには CQL を渡せます。

# Jira: JQL selects issues
atlassian-cli jira issue search \
  --jql "project = DEV AND status = 'In Progress' order by updated desc" \
  --format json | jq '.[].key'

# Confluence: CQL selects pages and other content
atlassian-cli confluence search cql \
  "space = DEV and type = page and title ~ 'runbook'" --limit 10

# Bitbucket: filter pull requests by state, no query language needed
atlassian-cli bitbucket --workspace myteam pr list api-service --state OPEN --limit 10

いずれも --format json で同じ構造化出力を返すため、API ごとの例外処理なしに製品をまたぐレポートを作れます。Jira で未解決のバグを数え、Confluence で古いページを一覧し、Bitbucket で未マージの PR を集計する。すべて同じ | jq の反射で書けます。CQL の詳しい解説は Confluence REST API ガイド、JQL のパターンは Jira REST API ガイドを参照してください。

ページネーションとレート制限の自動処理

ページネーションは、製品をまたぐスクリプトに静かにのしかかる税金です。Jira の従来のエンドポイントは startAt と maxResults によるオフセットページングを使います。Confluence v2 はカーソルページングで、次のページを Link ヘッダーで返します。Bitbucket は pagelen とあわせて next の URL を返します。3 製品それぞれにループを書くことになり、そのぶん境界のずれによるバグが生まれます。

CLI はそれをすべて隠します。--limit で欲しい件数を指定すれば、背後の API がどのページネーションモデルであっても、必要な件数が揃うまで CLI が辿ります。一括サブコマンドはさらに一歩進んで、スロットリングも加えます。

# Preview a bulk change first, always
atlassian-cli jira bulk transition \
  --jql "project = DEV AND status = Open" \
  --transition "In Progress" \
  --dry-run

# Bulk export across a whole project, pagination handled automatically
atlassian-cli jira bulk export \
  --jql "project = DEV" \
  --output issues.json --format json

Atlassian Cloud の API は、負荷をかけすぎると Retry-After のヒント付きで 429 レスポンスを返します。atlassian-cli はそのシグナルを尊重して自動的にバックオフするため、長時間のエクスポートや大きな jira bulk ジョブは、失敗する代わりに自分で速度を落とします。一括コマンドは --concurrency <n>（既定は 4）も受け付けるので、余裕のあるプランでは並列度を上げ、厳しいプランでは下げられます。確認プロンプトを備えた本番向けの実装は一括遷移のランブックにあります。

製品をまたぐスクリプト

API をまたぐ価値が出るのはここです。各コマンドは、どの API が応答したかにかかわらず同じ JSON を出力するため、1 つのスクリプトで 3 製品すべてからリリース状況のスナップショットを取得できます。

#!/bin/bash
# Release snapshot across Jira, Confluence, and Bitbucket
set -euo pipefail
PROFILE="work"
WS="myteam"

# 1. Open issues still blocking the release (Jira REST API)
atlassian-cli jira issue search --profile "$PROFILE" \
  --jql "project = DEV AND fixVersion = '2.0' AND status != Done" \
  --format json | jq 'length'

# 2. Release-notes pages tagged for review (Confluence REST API)
atlassian-cli confluence search cql --profile "$PROFILE" \
  "space = DEV and label = release-notes" --format json | jq 'length'

# 3. Open pull requests targeting the release branch (Bitbucket REST API)
atlassian-cli bitbucket --profile "$PROFILE" --workspace "$WS" \
  pr list api-service --state OPEN --format json | jq 'length'

echo "Release snapshot complete."

素の REST API に対して書くなら、このスクリプトには 3 つの認証設定、3 つのベース URL、3 つのページネーション処理が必要になります。CLI 経由なら、すべて同じ JSON を話す 3 行で済みます。これがJira、Confluence、Bitbucket を 1 つの CLI で扱うという観点の、実務上の核心です。

REST API を直接呼ぶべき場面

CLI は API の置き換えではなく、よく使う経路の近道です。素のエンドポイントを直接呼ぶ理由は、今でもいくつかあります。

• CLI がラップしていないエンドポイント。 Atlassian の REST の面は非常に広大です。ニッチなエンドポイントは curl と API トークンで直接呼び、よく使う操作だけを CLI に戻してください。
• Webhook のペイロードとイベントハンドラー。 Atlassian の側からこちらを呼んでくる場合は、CLI の有無にかかわらず生の JSON を解析することになります。
• フィールドの細かい制御。 CLI は多くのワークフローに必要なフィールドを公開しますが、独自の連携では生のレスポンス全体が欲しいこともあります。

現実的な線引きは、日常的な操作は atlassian-cli でスクリプト化し、ロングテールの部分だけ生の HTTP に降りることです。CLI は curl で使うのと同じプロファイルとトークンを読むため、行き来のコストはかかりません。CLI がラップしている範囲の一覧はコマンドリファレンスに、ターミナルでのワークフロー全体は atlassian-cli ガイドにあります。

よくある質問

関連リソース