Jira Service Management を自分のスクリプトと連携させる

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

Jira Service Management 連携の2つのパターン

Jira Service Management の連携の多くは、データが流れる2つの向きに集約されます。スタック内の何かがサービスデスクへ作業を押し込むか、サービスデスクがスタック内の何かを起動するかです。どちらも CLI と数行のシェルで作れ、REST クライアントは必要ありません。atlassian-cli がその接着剤になります。シェルコマンドを実行できるツール（監視、チャットボット、CI ジョブ、Webhook ハンドラー）なら、そのまま JSM を読み書きできます。

アウトバウンドのパターンは、スクリプトが CLI を呼び出してリクエストを作成または更新するものです。たとえば Prometheus のアラートがインシデントのリクエストを起票します。インバウンドのパターンは、JSM が自分の管理するエンドポイントに Webhook を送り、そのハンドラーが CLI を呼び出してリクエストにコメントし、遷移させ、振り分けるものです。以下ではすべて確認済みの jsm サブコマンドを使っています。応用する前に、コマンドリファレンスで確認してください。

アウトバウンド: イベントをリクエストに変える

アウトバウンドの連携すべての土台になるのが jsm request create です。数値のサービスデスク ID とリクエストタイプ ID、それに要約と説明を取ります。ID は一度調べて直接書き込んでもよく、動的に取得しても構いません。

# Discover the service desks and their IDs
atlassian-cli jsm service-desk list --limit 25

# List request types for service desk 10
atlassian-cli jsm request-type list --servicedesk-id 10 --limit 25

ID がわかれば、どのスクリプトからでも1つのコマンドでリクエストを起票できます。ここでは監視のアラートがインシデントを起票します。

# A monitor fires: open a JSM request and capture the key
KEY=$(atlassian-cli jsm request create \
  --servicedesk-id 10 \
  --request-type-id 7 \
  --summary "Disk usage critical on db-01" \
  --description "Root volume at 96%. Alert from Prometheus rule DiskFull." \
  --format json | jq -r '.issueKey // .key')

echo "Opened $KEY"

CLI は --format json を出力できるため、新しいリクエストキーを受け取って、同じスクリプト内でコメント、参加者の追加、遷移に再利用できます。構造化された出力というこの1点が、単発のコマンドを本物の連携に変えます。--format フラグは table、json、csv、yaml、quiet、markdown を受け付けるため、呼び出し方しだいで同じコマンドがダッシュボード、表計算、CI のゲートに使えます。

早めに手当てしておきたい点が1つあります。うるさいアラートが再発火するたびに重複したリクエストを作らないことです。作成の前に jsm request list --servicedesk-id 10 --format json をさっと実行し、同じホストやアラート ID を参照する未対応のリクエストがないかを確認します。あれば新規作成ではなく、既存のキーにコメントします。このガード1つで、不安定なチェックが1時間に10回発火してもキューが荒れません。

コードからリクエストにコメントし、遷移させ、振り分ける

リクエストができたあと、連携が時間を費やすのはその更新です。CLI はエージェントがポータルで行う操作を反映するため、スクリプトから報告者に受付を伝え、リクエストをワークフローに沿って進め、適切な対応者を引き込めます。

# Post a public reply the customer can see
atlassian-cli jsm request add-comment SD-123 \
  --body "Thanks, we are investigating and will update within 30 minutes." \
  --public

# Post an internal-only note (omit --public)
atlassian-cli jsm request add-comment SD-123 \
  --body "Paged on-call via the alert integration."

# Inspect the available transitions, then move the request
atlassian-cli jsm request transitions SD-123
atlassian-cli jsm request transition SD-123 --transition "In Progress"

# Add the responding engineer as a participant
atlassian-cli jsm request add-participant SD-123 --account-id 5f0a1b2c3d

add-comment の --public フラグは、顧客に見える返信と内部メモを分けるもので、ボットがチームに代わって投稿するときに効いてきます。ワークフローの名前はプロジェクトによって異なり、文字列が違うとコマンドが失敗するため、まず jsm request transitions を呼んで、そのリクエストタイプの正確な遷移名を読み取ってください。

何をするか決める前に現在の状態が必要ですか。jsm request status SD-123 はリクエストのステータスを返し、jsm request get SD-123 はオブジェクト全体を返します。どちらも jq に通せば、結果に応じて自動化を分岐できます。

違反する前に SLA を監視してエスカレーションする

もっとも価値のある JSM の連携は、リクエストだけでなく SLA に対して動くものです。CLI はポータルが表示するのと同じ SLA 指標を公開するため、定期ジョブがリクエストの残り時間を読み取り、目標を逃す前にエスカレーションできます。

# List all SLA metrics on a request
atlassian-cli jsm sla list SD-123 --format json

# Read one specific SLA, e.g. time to resolution
atlassian-cli jsm sla get SD-123 --sla-id time-to-resolution --format json

まず JSON を確認して、そのインスタンスで残り時間を保持しているフィールドを見つけ、それで分岐します。cron ジョブが未対応のキューをたどり、違反間近のものに対応できます。

# Nightly: export the open queue, check SLAs, escalate
atlassian-cli jsm queue issues 10 5 --format csv > open-queue.csv

# For a flagged request, add the incident manager and comment
atlassian-cli jsm request add-participant SD-123 --account-id 6a1b2c3d4e
atlassian-cli jsm request add-comment SD-123 \
  --body "SLA approaching breach, escalated to incident manager."

キューのコマンド（jsm queue list 10、jsm queue get 10 5、jsm queue issues 10 5）は、数値のサービスデスク ID に続けてキュー ID を取ります。ページ送りは自動なので、件数にかかわらず一致するリクエストをすべて取得できます。

インバウンド: CLI を呼び出す Webhook ハンドラー

インバウンドの連携は、Atlassian 側で登録する Webhook（JSM の自動化またはサイト管理から設定）から始まり、自分が所有する HTTP エンドポイントを指します。リクエストが作成または更新されると、JSM はそのエンドポイントに JSON のペイロードを送ります。ハンドラーはペイロードからリクエストキーを読み取り、CLI を呼び出して処理します。

Webhook 自体は CLI から設定しませんが、サイトにすでにある Webhook を確認して、連携どうしがぶつからないようにできます。

# List webhooks registered on the site (JSM runs on Jira)
atlassian-cli jira webhooks list

最小限のハンドラーは数行で済みます。エンドポイントを動かすもの（サーバーレス関数、小さなサーバー、キューのワーカー）は、手で実行するのと同じコマンドを呼べます。

#!/bin/bash
# webhook-handler.sh: called with the JSM payload on stdin
set -euo pipefail
# Unattended runs assume no default profile: pass --profile on every command

PAYLOAD=$(cat)
KEY=$(echo "$PAYLOAD" | jq -r '.issue.key')

# Auto-acknowledge every newly created request
atlassian-cli jsm request add-comment "$KEY" \
  --body "Received. A team member will respond shortly." \
  --public --profile prod

# Route hardware requests straight to In Progress
if echo "$PAYLOAD" | jq -e '.issue.fields.summary | test("hardware"; "i")' > /dev/null; then
  atlassian-cli jsm request transition "$KEY" --transition "In Progress" --profile prod
fi

CLI を連携の層として使う意味はここにあります。同じコマンドが対話的にも、cron ジョブでも、Webhook ハンドラーの中でも動きます。バージョンを管理する SDK はなく、言語ごとに OAuth の手順を実装し直す必要もなく、手で試した内容と本番で動く内容に差がありません。

無人実行のスクリプトでの認証

連携は人がいない状態で動くため、認証は非対話でなければなりません。名前付きプロファイルを一度設定し、各コマンドで、あるいは --profile フラグで参照します。

# One-time interactive setup on a trusted machine
atlassian-cli auth login

# Verify the session in CI without printing anything
atlassian-cli auth test --profile prod --format quiet && echo OK

# Use the profile in an integration command
atlassian-cli jsm request list --servicedesk-id 10 --limit 25 --profile prod

--format quiet モードは終了コードを設定して何も出力しないため、CI のゲートに最適です。認証情報が欠けていたり期限切れだったりすると、パイプラインが止まります。環境ごとに分けるには、ステージング用と本番用でプロファイルを分けておけば、テスト用のスクリプトが本番のサービスデスクに触れることはありません。トークンの保存や CI の環境変数を含む設定全体は、認証ガイドで解説しています。

連携レシピ一覧

よくあるトリガーと、それを処理する CLI コマンドの対応表です。以下のコマンドはいずれも実在のサブコマンドで、リファレンスで確認できます。

サービスデスクのコマンド（顧客、組織、承認、リクエストタイプ）をより広く見るには、JSM CLI ガイドをご覧ください。エンドポイントを直接扱いたい場合は、Jira Service Management API の解説が、CLI がラップしている生の呼び出しを扱っています。ヘルプセンターの回答をこれらのフローに組み込むには、CLI から使う JSM のナレッジベースの記事が jsm kb search の使いどころを示しています。

よくある質問

関連リソース