スクリプトで Atlassian を自動化する: 実践プレイブック

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

そもそもなぜ Atlassian をスクリプト化するのか

Jira の自動化と Atlassian スイート全体の自動化への最短ルートは、ルールエンジンでもサードパーティの連携プラットフォームでもありません。コマンドラインツールを 1 つ呼ぶシェルスクリプトです。atlassian-cli という 1 つの無料バイナリが Jira、Confluence、Bitbucket、Jira Service Management をカバーするため、同じスクリプトで課題を検索し、wiki ページを公開し、プルリクエストを作成し、サポートのリクエストにコメントするところまで、ターミナルから離れずに行えます。

これは製品横断のプレイブックです。Jira 自動化の実例にあるルールごとのレシピとは意図的に異なります。1 つの製品に絞るのではなく、どの Atlassian 製品に向けても変わらないスクリプトのパターンを扱います。一度覚えれば、4 つの製品をつなぎ、定期実行、CI、オンデマンドで動くパイプラインに組み立てられます。

このツールについての注記。atlassian-cli は MIT ライセンスの、コミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。ベンダーによる一次サポートが必要なときは公式の acli を、Jira、Confluence、Bitbucket、JSM をまたぎ、スクリプト向けに一貫した JSON、CSV、YAML 出力を備えた単一バイナリが欲しいときは atlassian-cli を使ってください。

すべてのスクリプトに共通する構成要素

自動化を書き始める前に、すべての atlassian-cli スクリプトが使い回す小さな語彙を知っておくと役立ちます。これから作るプレイブックのほとんどは、この 5 つの考え方の組み合わせです。

このうち 2 つは詳しく見ておく価値があります。1 つ目はプロファイルです。サイトごとに一度認証して既定を指定しておけば、どのスクリプトからも名前で参照できます。

# Save a profile once (token comes from an env var, never inline)
atlassian-cli auth login --profile prod \
  --base-url https://acme.atlassian.net \
  --email you@acme.com \
  --token "$ATLASSIAN_TOKEN" --default

# Confirm it works before a script does anything else
atlassian-cli auth test --profile prod --format quiet

2 つ目は JSON と jq の組み合わせです。どの製品も同じ構造化出力を返すため、1 つの考え方がどこでも通用します。--envelope フラグは出力の形を予測可能にするので、jq のフィルターは最上位の構造を推測する代わりに .data[] と書けます。

# List issue keys, one per line
atlassian-cli jira issue search \
  --jql "project = ENG AND status = Done" \
  --format json --envelope | jq -r '.data[].key'

フラグの一覧はコマンドリファレンスと認証ガイドを別タブに開いておいてください。以下の内容はすべて、この基本要素から組み立てています。

Jira の自動化: 入り口として

多くのチームは、まず Jira の自動化から始めます。作業が集まる場所だからです。最初のスクリプトは危険なことをしないものが向いています。読み取りだけです。JQL クエリを、スタンドアップの連絡やレポートに貼れる整形済みのダイジェストに変えてみましょう。

#!/usr/bin/env bash
set -euo pipefail
PROFILE=prod

# Everything closed in the active sprint, as a bullet list
atlassian-cli jira issue search \
  --profile "$PROFILE" \
  --jql "project = ENG AND sprint in openSprints() AND status = Done" \
  --format json --envelope \
  | jq -r '.data[] | "- \(.key): \(.fields.summary)"'

読み取りが期待どおりに動いたら、書き込みを足します。単一課題向けの動詞は一括版と同じ形なので、まず 1 件の課題で試し、同じロジックをそのまま jira bulk 系で JQL の結果全体に広げられます。データを変更する処理の鉄則は、まずドライラン、それから実行です。

# Preview a bulk transition (no changes made)
atlassian-cli jira bulk transition \
  --profile prod \
  --jql "project = ENG AND status = 'In Review' AND updated < -14d" \
  --transition "Done" \
  --dry-run

# Reassign stale unassigned bugs to the triage lead
atlassian-cli jira bulk assign \
  --profile prod \
  --jql "project = ENG AND type = Bug AND assignee is EMPTY" \
  --assignee triage-lead@acme.com

個別の更新も同じ形です。クエリではなく特定の課題 1 件に反応させたいときに便利です。

atlassian-cli jira issue transition ENG-482 --transition "In Progress"
atlassian-cli jira issue update ENG-482 --summary "Rename service to billing-api"
atlassian-cli jira issue assign ENG-482 --assignee you@acme.com

引数の解析と確認プロンプトを備えた、一括ワークフローの本番向け実装は一括遷移のランブックを参照してください。

1 つのスクリプトで製品をつなぐ

単一バイナリの価値が出るのがここです。Jira、Confluence、Bitbucket、JSM がすべて同じコマンドの背後にあるため、スクリプトは製品から製品へ、ただのシェル変数でデータを渡せます。API クライアントも、つなぎのコードも、認証ライブラリの使い分けも不要です。

Jira から Confluence へ: リリースノートの自動生成

リリースに含まれた課題を集め、そのまま Confluence のページとして公開します。

#!/usr/bin/env bash
set -euo pipefail
PROFILE=prod
SPACE=ENG
VERSION="2026.7"

# 1. Pull completed issues for the release version
items=$(atlassian-cli jira issue search \
  --profile "$PROFILE" \
  --jql "project = ENG AND fixVersion = \"$VERSION\" AND status = Done" \
  --format json --envelope \
  | jq -r '.data[] | "<li>\(.key): \(.fields.summary)</li>"')

# 2. Publish them as a Confluence page
atlassian-cli confluence page create \
  --profile "$PROFILE" \
  --space "$SPACE" \
  --title "Release notes $VERSION" \
  --body "<h2>Shipped in $VERSION</h2><ul>$items</ul>"

全体の流れは、変数でつないだ 2 つのコマンドだけです。ページではなく日付付きのブログ記事にしたい場合は、confluence page create を confluence blog create に置き換えてください。

同じ流れに Bitbucket と JSM を組み込む

複数のリポジトリで何が開いているかを確認するのも、読み取りから始めるパターンです。プルリクエストを一覧し、それから操作します。

# Open PRs on a repo, newest activity first
atlassian-cli bitbucket --workspace acme pr list api-service \
  --state OPEN --limit 20

# Comment on a specific PR from a script
atlassian-cli bitbucket --workspace acme pr comment api-service 123 \
  --text "Automated check passed. Ready for human review."

Jira Service Management も同じように組み込めます。自動デプロイのチェックが失敗したときにリクエストを作成しておけば、その障害を最初から追跡できます。

atlassian-cli jsm request create \
  --servicedesk-id 10 \
  --request-type-id 7 \
  --summary "Deploy failed: api-service on main" \
  --description "Pipeline failed at the integration stage. Investigating."

# Later, add a public update on the same request
atlassian-cli jsm request add-comment SD-123 \
  --body "Root cause found, fix deploying now." --public

これらのコマンドは互いを一切知りません。そこが要点です。それぞれが予測可能な出力を返すため、Jira のクエリから Confluence のページ、Bitbucket のコメント、JSM のリクエストへとつなぐのに必要なオーケストレーションはシェルだけです。

無人実行のための安全策

手で実行して結果を見ているスクリプトは多少の失敗が許されます。定期実行のスクリプトはそうではありません。誰も見ていないときでも自動化を安全に保つ習慣が 3 つあります。

1. 認証で門番を置く。 すべてのスクリプトを atlassian-cli auth test --profile prod --format quiet で始めてください。トークンが期限切れなら、バッチの途中で失敗するのではなく、データに触れる前に停止します。
2. 破壊的なコマンドはドライランする。 Jira、Confluence、Bitbucket のすべての一括コマンドが --dry-run に対応しています。実行して件数を確認し、意図した数と一致したときだけフラグを外してください。範囲の広すぎるクエリは、誤った一括更新の最も多い原因です。
3. 早期に失敗させる。 スクリプトの冒頭に set -euo pipefail を置き、1 つのコマンドの失敗でパイプライン全体を止め、エラーが後続の処理に波及しないようにします。

4 つ目のレバーは並列数です。一括操作は既定で複数のリクエストを並行して実行します。--concurrency フラグで、大きなバッチでは上げ、レート制限の厳しいサイトでは下げられます。API がスロットリングのレスポンスを返すと CLI は自動的にバックオフするため、強気な設定でも恒久的な失敗にはなりません。

# Preview first, then run with lower concurrency on a strict plan
atlassian-cli confluence bulk add-labels \
  --cql "space = DOCS AND type = page" \
  --labels reviewed \
  --dry-run

atlassian-cli confluence bulk add-labels \
  --cql "space = DOCS AND type = page" \
  --labels reviewed \
  --concurrency 2

スケジュール実行: cron と CI

atlassian-cli は環境変数からトークンを読む単一バイナリなので、追加の設定なしにどのスケジューラーにも組み込めます。夜間の整理スクリプトを実行する cron のエントリーは次のようになります。

# crontab -e : run the sprint digest every weekday at 09:00
0 9 * * 1-5  ATLASSIAN_TOKEN=... /home/ci/scripts/sprint-digest.sh >> /var/log/atlassian.log 2>&1

CI でも考え方は同じです。API トークンはマスクされたシークレットとして保存し、ATLASSIAN_TOKEN として渡します。認証情報が誤っている場合にパイプラインがきれいに失敗するよう、quiet の認証チェックでジョブに門番を置いてください。

# A CI step: block the job unless auth succeeds
atlassian-cli auth test --profile prod --format quiet \
  && ./scripts/publish-release-notes.sh

これを確実にしているのが --format quiet と --format json の出力です。quiet は制御用のきれいな終了コードを、JSON は後続ステップが解析できる機械可読なデータを返します。ここで使ったコマンドを印刷できる形でまとめたものは atlassian-cli チートシートに、インストールと初回セットアップは atlassian-cli ガイドにあります。

よくある質問

関連リソース