Jira Service Management を CLI から自動化する

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

CLI によるサービスデスク自動化とは

コマンドラインからのサービスデスク自動化とは、クリック操作の代わりにコマンドとスクリプトで Jira Service Management（JSM）を動かすことです。リクエストの起票、キューの処理、ワークフローに沿ったリクエストの前進、SLA タイマーの確認を、単一のターミナルバイナリから行えます。エージェント向けポータルで繰り返している作業は、シェルスクリプト、cron ジョブ、CI のステップに包めば、毎回同じ手順で実行できます。

この記事では、atlassian-cli を使ったその流れを一通り紹介します。サービスデスク自動化に必要な3つの要素、つまりリクエスト（受付と更新）、キュー（チームが処理中の内容）、SLA（期限内に対応できているか）を扱います。さらに詳しい内容は、リクエスト管理と、その土台となる Jira Service Management API の記事に続きます。

コマンドの前に1点だけ補足します。atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。Atlassian が提供する公式 CLI（acli）でもありません。ベンダーによる一次サポートが必要であれば公式の acli を、Jira、Confluence、Bitbucket、JSM を MIT ライセンスの無料の単一 Rust バイナリでカバーしたい場合は atlassian-cli を選んでください。

セットアップ: 認証とデスクの確認

自動化はまず認証情報の保存から始まります。スクリプトを無人で動かすためです。API トークンで一度認証し、あとから再利用できる名前をプロファイルに付けてください。

# Store a reusable profile (API token from id.atlassian.com)
atlassian-cli auth login \
  --profile support \
  --base-url https://your-org.atlassian.net \
  --email you@your-org.com \
  --token $JSM_TOKEN \
  --default

その上に何かを組み立てる前に、プロファイルが実際に動くことを確認します。auth test コマンドは認証情報が誤っていると 0 以外の終了コードを返すため、どのスクリプトでも冒頭に置くのに適しています。

# Verify the credential before running automation
atlassian-cli auth test --profile support --format quiet && echo "auth ok"

JSM のコマンドはどれも、ポータルに表示されるプロジェクトキーではなく内部のサービスデスク ID を受け取ります。まずデスクを一覧して ID を確認してください。

# List service desks and note the numeric id
atlassian-cli jsm service-desk list --limit 25

# Inspect one desk in detail
atlassian-cli jsm service-desk get 10

リクエストはリクエストタイプに対して起票します。リクエストタイプにもデスクごとの数値 ID があります。作成用スクリプトが正しいタイプを指すよう、デスクのタイプを一覧しておきましょう。

# Request types available on service desk 10
atlassian-cli jsm request-type list --servicedesk-id 10 --limit 25

# Which fields a request type expects
atlassian-cli jsm request-type fields 10 7

コマンド一覧

細部に入る前に、jsm 全体の構成を見ておきます。サービスデスク自動化のほとんどは、これらの部品の組み合わせです。どのコマンドもグローバルな --format json フラグを受け付けるため、いずれもスクリプトの入力にできます。

リクエスト受付の自動化

もっとも効果が大きい自動化は、他システムからのシグナルをリクエストに変えることです。監視アラート、フォームの送信、定期チェックのいずれも、人がポータルに入力する代わりに1つのコマンドで JSM のリクエストを起票できます。

# Create a request from a script
atlassian-cli jsm request create \
  --servicedesk-id 10 \
  --request-type-id 7 \
  --summary "Access issue" \
  --description "Can't log in"

リクエストができてしまえば、その後のライフサイクルもスクリプト化できます。現在のステータスを読み取り、報告者がポータルで見られる公開返信を追加し、内部メモを残せます。

# Read one request and its current status
atlassian-cli jsm request get SD-123
atlassian-cli jsm request status SD-123

# Public reply visible to the customer
atlassian-cli jsm request add-comment SD-123 \
  --body "Investigating, we'll update you shortly." \
  --public

# Add a watcher so an on-call engineer is looped in
atlassian-cli jsm request add-participant SD-123 --account-id 5f...1a

受付内容をまとめて確認するには、デスクのリクエストをすべて一覧し、後続ツール向けに出力を JSON へ切り替えます。--envelope フラグを付けると、一覧結果が {"data": [...], "count": N} オブジェクトで包まれ、スクリプトで解析しやすくなります。

# All requests on a desk, as parseable JSON
atlassian-cli jsm request list \
  --servicedesk-id 10 \
  --limit 50 \
  --format json --envelope | jq '.count'

ターミナルからキューを処理する

JSM のエージェントは、次に何を対応するかをキューで判断します。CLI からキューを読み取れば、UI に触れずに独自のダッシュボード、負荷レポート、アラートを作れます。まずデスクのキューを一覧し、次に ID を指定して特定のキュー内の課題を取得します。

# List the queues configured on service desk 10
atlassian-cli jsm queue list 10

# Inspect one queue's definition
atlassian-cli jsm queue get 10 5

# Pull the issues currently in queue 5
atlassian-cli jsm queue issues 10 5 --limit 25

--format json と jq を組み合わせれば、キューのデータから「未割り当てのリクエストがいくつ待っているか」といった問いに、Jira を開かずに答えられます。たとえば、定期チェックとしてキュー内の課題数を数えられます。

# Count issues waiting in the triage queue
atlassian-cli jsm queue issues 10 5 \
  --format json | jq '. | length'

コマンドは失敗時に 0 以外で終了し、成功時には構造化データを出力します。そのため、朝のサマリーをチームチャットに投稿する cron ジョブや、インシデントのキューがしきい値を超えたらデプロイを止める CI ゲートにそのまま組み込めます。

マネージャーが開ける週次レポートにするなら、形式を CSV に変えてファイルに書き出します。スクリプトを動かすのと同じデータが、追加のツールなしでスプレッドシートになります。

# Export a queue's issues to CSV for a weekly review
atlassian-cli jsm queue issues 10 5 \
  --format csv > triage-queue.csv

SLA をプログラムから追跡する

SLA はサービスデスクの要です。約束した時間内に応答し、解決できているかどうかを示します。CLI は任意のリクエストの SLA タイマーを読み取れるため、月次レポートで気づくのではなく、違反が起きる前に検知できます。

# Every SLA metric on a request
atlassian-cli jsm sla list SD-123

# One specific metric, e.g. time to resolution
atlassian-cli jsm sla get SD-123 --sla-id time-to-resolution

本当の価値は、SLA の取得とキューの取得を定期実行で組み合わせたときに生まれます。キュー内の未解決の課題を取得し、それぞれの SLA を確認して、違反間近のものを表に出します。JSON では進行中のサイクルに残り時間が含まれるため、短いスクリプトでもエスカレーション対象を判断できます。

# Loop the triage queue and print SLA state per request
for key in $(atlassian-cli jsm queue issues 10 5 --format json | jq -r '.[].key'); do
  echo "== $key =="
  atlassian-cli jsm sla get "$key" --sla-id time-to-resolution --format json
done

これがサービスデスク自動化のもっとも有用な形です。人が忘れずに確認しなければならない数値を、定期ジョブが代わりに見張ってくれます。

スクリプトでの承認と遷移

サービスデスクのワークフローの多くは承認で止まります。マネージャーの承認が必要なアクセス権のリクエストや、レビューが必要な変更などです。承認もワークフローの遷移もスクリプト化できるため、対応プロセスの定型部分を自動化できます。

# See pending approvals on a request
atlassian-cli jsm approval list SD-123

# Approve or decline a specific approval
atlassian-cli jsm approval approve SD-123 --approval-id 1
atlassian-cli jsm approval decline SD-123 --approval-id 1

遷移はリクエストをワークフローに沿って進めます。有効な遷移先はリクエストの現在のステータスによって変わるため、必ず先に利用可能な遷移を確認してください。

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

エンドツーエンドの実例

これまでの要素をまとめた小さなスクリプトを示します。アラートからリクエストを起票し、内部メモを追加し、解決までの SLA を出力して、オンコール担当者がすぐに残り時間を確認できるようにします。監視の Webhook から起動する、いわば接着剤のようなスクリプトです。

#!/bin/bash
# Raise a JSM request from an alert and report its SLA
set -euo pipefail

PROFILE="support"
DESK=10
TYPE=7

# Step 1: create the request, capture its key from JSON
KEY=$(atlassian-cli jsm request create \
  --profile "$PROFILE" \
  --servicedesk-id "$DESK" \
  --request-type-id "$TYPE" \
  --summary "[auto] Checkout latency high" \
  --description "p95 latency breached threshold at $(date -u)" \
  --format json | jq -r '.issueKey // .key')

echo "Created $KEY"

# Step 2: add an internal note for the on-call engineer
atlassian-cli jsm request add-comment "$KEY" \
  --profile "$PROFILE" \
  --body "Auto-raised from alerting. Runbook: check the checkout service dashboard."

# Step 3: print the time-to-resolution SLA so the clock is visible
atlassian-cli jsm sla get "$KEY" \
  --profile "$PROFILE" \
  --sla-id time-to-resolution

echo "Done."

ここに出てくるコマンドはすべて実在するサブコマンドで、いずれも --profile を受け付けます。値を1つ差し替えるだけで、同じスクリプトをステージングにも本番にも向けられます。書き込みを伴う処理を組む前に、まず読み取り専用の呼び出し（service-desk list、queue issues、sla list）で ID を確認してください。JSM の各コマンドのフラグ一覧はコマンドリファレンスを参照してください。

よくある質問

関連リソース