Atlassian API トークンと PAT の違い: CLI の認証

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

API トークンと PAT、CLI にはどちらが必要か

コマンドラインツールを Atlassian につなぐ場合、結論はこうです。atlassian api token は Atlassian Cloud（*.atlassian.net のインスタンス）で作成するもの、パーソナルアクセストークン（PAT）は Data Center または Server で作成する相当物です。どちらもスクリプトをユーザーとして認証するという同じ課題を解決しますが、作成場所も認証方式も異なります。自分の Jira、Confluence、Bitbucket が実際にどこで動いているかに合わせて選んでください。

ここは本当に混同されやすいところです。r/jira では、Data Center の自動化用ユーザーについて「PAT と OAuth のどちらにするか」を検討するスレッドがよく立つ一方で、その隣では Cloud のユーザーが PAT の画面を見つけられずに困っています。Cloud にはそもそもその画面がないからです。atlassian-cli は Atlassian Cloud を対象としているため、Jira、Confluence、Jira Service Management では常に API トークンを使うことになります。選択肢がもう少しあるのは Bitbucket Cloud だけで、これは後述します。

Atlassian API トークンとは

Atlassian API トークンは、自分の Atlassian アカウントに紐づく長いランダム文字列です。アカウントのメールアドレスと組み合わせ、CLI は両方を HTTP Basic 認証として送信します。認証されるのはあなた自身です。ブラウザーで Jira、Confluence、JSM に対してできることは、そのトークンを持つツールが REST API 経由で同じようにできます。

作成場所は個々の Jira や Confluence のサイトではなく、アカウントのセキュリティ設定です。

1. id.atlassian.com/manage-profile/security/api-tokens を開きます。
2. Create API token をクリックし、内容がわかるラベルを付けます（たとえば laptop-cli や ci-release-bot）。
3. 値はすぐにコピーします。Atlassian は一度しか表示しないため、失くした場合は新しく作り直します。

トークンは特定のプロジェクトではなくアカウント全体に紐づくため、漏れたときの重大さはパスワードと同じです。シェル履歴に残るような形で、コマンドラインに直接貼り付けないでください。まず環境変数に入れます。

# Load the token into a variable so it stays out of history
export ATLASSIAN_API_TOKEN="paste-your-token-here"

PAT と Bitbucket アクセストークンの位置づけ

パーソナルアクセストークンは Data Center と Server の世界のものです。セルフホストの Jira や Confluence では、そのサーバー内の Profile の Personal Access Tokens から PAT を作成し、Basic 認証ではなく Bearer トークンとして送信します。有効期限を設定でき、これらのデプロイ形態ではスクリプトや自動化用ユーザーの標準的な選択肢です。インスタンスの URL が atlassian.net ではなく自社ドメインであれば、こちらのトークンモデルになります。

その中間にあって面白いのが Bitbucket Cloud です。現行の認証情報が 2 種類あり、そのうち 1 つはスコープを絞った PAT によく似た動きをします。

• 個人アカウント向けの API トークン（Basic 認証）。id.atlassian.com/manage-profile/security/api-tokens で Bitbucket にスコープを絞った Atlassian API トークンを作成し、メールアドレスと組み合わせて使います。
• 単一のリポジトリ、プロジェクト、ワークスペースにスコープを絞ったアクセストークン（Bearer 認証）。対象リソースの Settings の Access tokens から作成し、付与したスコープ（たとえば repository:read、pullrequest:write）だけを持たせます。Data Center の PAT に Cloud で最も近い存在で、CI にはこれが適しています。

CLI にログインする

atlassian-cli は認証情報をプロファイル単位で保存するため、個人用のインスタンスと業務用のインスタンスを併存させられます。auth login コマンドで一度書き込めば、あとはプロファイル名を指定するだけです。詳細は認証ガイドに記載しています。

Jira、Confluence、JSM（Cloud の API トークン）

atlassian-cli auth login \
  --profile work \
  --base-url https://your-domain.atlassian.net \
  --email you@company.com \
  --token $ATLASSIAN_API_TOKEN \
  --default

--base-url には https:// を含め、末尾のスラッシュは付けません。--default を指定すると、--profile を省略したときに使われるプロファイルになります。信頼して使う前に動作を確認します。

atlassian-cli auth test --profile work
atlassian-cli jira issue search --jql "project = DEV" --limit 1

Bitbucket、個人アカウント（API トークン、Basic 認証）

atlassian-cli auth login \
  --profile work \
  --bitbucket \
  --email you@company.com \
  --token $BITBUCKET_TOKEN

Bitbucket、CI 向けにスコープを絞る（アクセストークン、Bearer 認証）

atlassian-cli auth login \
  --profile bb-ci \
  --bitbucket --bearer \
  --token $BITBUCKET_TOKEN

Bearer 認証では --email は不要です。Bitbucket の認証情報は atlassian-cli auth test --bitbucket --profile bb-ci で個別に確認できます。認証情報は AES-256-GCM で暗号化され、ローカルの設定ディレクトリに書き込まれます。このプロジェクトや Web サイトが受け取ることはありません。

トークンの種類の一覧

atlassian-cli の構成は、ほぼこの 4 種類の認証情報でカバーできます。それぞれの作成場所、認証方式、ログイン時のフラグをまとめました。

パターンは一貫しています。Cloud のユーザー認証情報はメールアドレスを伴う Basic 認証、スコープを絞ったトークンとセルフホストのトークンはメールアドレス不要の Bearer 認証です。401 が返るときは、メールアドレスがトークンの所有者と一致していないか、Basic を期待している箇所に Bearer トークンを送っていることがほとんどです。

CI のログにトークンを残さない

CI では、認証情報のファイルをイメージに焼き込みたくはありません。atlassian-cli は環境変数で保存済みのトークンを上書きできるため、害のないプロファイルのメタデータ（ベース URL、メールアドレス）だけをコミットし、本物のシークレットは実行時に渡せます。トークンの環境変数は次の順に確認されます。

• ATLASSIAN_CLI_TOKEN_<PROFILE>。プロファイルごとの上書きで、プロファイル名は大文字にします（例: ATLASSIAN_CLI_TOKEN_CI）。
• ATLASSIAN_API_TOKEN。有効なプロファイルが共通で使うフォールバックです。
• Bitbucket の場合: ATLASSIAN_CLI_BITBUCKET_TOKEN_<PROFILE>、ATLASSIAN_BITBUCKET_TOKEN、または短い BITBUCKET_TOKEN。

次の GitHub Actions のステップでは、使い捨てのプロファイルでログインし、トークンはリポジトリのシークレットから取得します。シークレットはログ上でマスクされ、リポジトリにも書き込まれないため、履歴にもビルド出力にも残りません。

# GitHub Actions: token from a secret, profile metadata inline
- name: Query Jira
  env:
    ATLASSIAN_API_TOKEN: ${{ secrets.ATLASSIAN_API_TOKEN }}
  run: |
    atlassian-cli auth login \
      --profile ci --base-url https://mycompany.atlassian.net \
      --email bot@mycompany.com --default
    atlassian-cli jira issue search --jql "project = REL" --format json

いくつかの習慣で安全性は大きく高まります。個人のトークンではなく専用のサービスアカウントを使う、Bitbucket の作業では全体的な API トークンではなくリポジトリやワークスペースのアクセストークンにスコープを絞る、定期的にローテーションして漏れた値の有効期間を短くする、といったことです。接続確認だけを行う CI のゲートには atlassian-cli auth test --format quiet && echo OK が使えます。失敗時に機密情報を出力せずに非ゼロで終了します。

acli との違い

atlassian-cli は、コミュニティによる独立したオープンソースプロジェクトです。Atlassian が提供する公式 CLI（acli）ではありません。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。ベンダーのサポートが必要なときは公式の acli を、ここで説明したプロファイル単位でトークンを中心に据えた認証モデルで、Jira、Confluence、Bitbucket、JSM をひとつの無料バイナリからまとめて扱いたいときは atlassian-cli を選んでください。トークンの種類自体はどちらでも同じです。いずれも Atlassian の認証情報であり、この記事はどれを作成すべきかを説明するもので、独自方式の話ではありません。

両者をより広く比較したい場合は acli と atlassian-cli の比較をご覧ください。ひとつの認証情報ですべての製品に届く点に魅力を感じるなら、Jira、Confluence、Bitbucket をひとつの CLI でが、その製品横断のワークフローを解説しています。

よくある質問

関連リソース