Jira の JQL クエリをターミナルから実行して保存する

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

Jira の JQL クエリをコマンドラインから実行するには、クエリ文字列を atlassian-cli jira issue search --jql に渡します。CLI は JQL を Jira Cloud の検索 API に送り、一致した課題をテーブル、JSON、CSV、YAML、markdown のいずれかで表示します。要点はこれだけで、以下はすべてこの上に積み上がります。

この記事は JQL の構文リファレンスではありません。演算子、関数、フィールドの例が知りたい場合は JQL クエリチートシートをお読みください。ここで扱うのは、JQL をターミナルから実行するときの実務です。出力の整え方、結果をほかのツールへ流す方法、そして毎日実行するクエリを保存して二度と打ち直さないようにする方法です。すべてのコマンドで atlassian-cli を使います。これは Jira の Web UI と同じ公開 REST API を呼び出す、独立したオープンソースのバイナリです。

Jira の JQL クエリをコマンドラインから実行する

中心となるコマンドは jira issue search です。--jql に文字列を渡すと、一致した課題が返ってきます。大きな結果を取ってくる前にクエリが正しいか確認できるよう、まずは --limit で小さく始めます。

# Ten most recently created issues in a project
atlassian-cli jira issue search \
  --jql "project = DEV ORDER BY created DESC" \
  --limit 10

既定の出力は人が読みやすいテーブルなので、ちょっと確認したいだけならこのままで十分使えます。JQL の句は、Jira の課題ナビゲーターに打ち込むのとまったく同じ形で渡せます。JQL は値に単引用符を使えるので、外側のシェルの引用は単純なままに保てます。

# Everything assigned to you that is still open
atlassian-cli jira issue search \
  --jql "assignee = currentUser() AND resolution = Unresolved ORDER BY updated DESC"

# In-progress work on one project, newest first
atlassian-cli jira issue search \
  --jql "project = DEV AND status = 'In Progress' ORDER BY updated DESC" \
  --limit 20

Jira の課題ナビゲーターで動く JQL は、ここでもそのまま動きます。currentUser()、openSprints()、membersOf() のような関数も、-7d や startOfWeek() のような相対日付も同様です。実務的なコツは、複雑なクエリはまず Web のナビゲーターで下書きし、期待どおりの結果が返ることを確かめてから、その JQL 文字列を --jql フラグにコピーすることです。そこから先、クエリは持ち運び可能になります。手を加えずにエイリアス、スクリプト、スケジュール実行のジョブへそのまま置けます。

複数のサイトを管理している場合は、--profile <name> を足せば同じクエリを別のインスタンスに向けられます。プロファイルは auth login で一度設定し、~/.atlassian-cli/config.yaml に保存されます。フラグの一覧はコマンドリファレンスをご覧ください。このページの例はどれも、既定に設定されたプロファイル、または明示的に指定したプロファイルに対して動きます。

出力形式を選ぶ

Web のナビゲーターからコピー＆ペーストするより CLI が優れている理由が --format フラグ（短縮形は -f）です。同じ JQL クエリから、読むためのテーブル、スクリプト用の JSON、表計算用の CSV、課題に貼り付ける markdown を作り分けられます。そのデータで次に何をするかに合わせて形式を選んでください。

markdown と quiet は見落とされがちですが、十分に役に立ちます。markdown の出力はプルリクエストの説明、Jira のコメント、Confluence ページにきれいに貼り付けられるので、生きたクエリから作る進捗報告に便利です。quiet は何も表示せず、終了コードだけで結果を伝えるので、クエリをゲートとして使えます。CI で実行し、結果が空でなければビルドを失敗させる、といった使い方です。

JSON を相手にスクリプトを書くときは、追加のフラグが 2 つ効いてきます。--output <file> は結果を標準出力ではなくファイルに直接書き出し、--envelope は一覧出力を {"data": [...], "count": N} で包んで、行数をデータと一緒に運びます。

# Write results to a file instead of the terminal
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug" \
  --format json --output bugs.json

# Wrap the array so you get {"data": [...], "count": N}
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug" \
  --format json --envelope

JQL の結果を jq に流す

コマンドラインがブラウザーを引き離すのは JSON 出力の場面です。結果を jq に流せば、JQL の結果を必要なフィールドだけに整え直したり、数を数えたり、表計算を開かずに簡単なレポートを組み立てたりできます。

# Just the issue keys
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug" \
  --format json | jq '.[].key'

# Key and summary as tab-separated columns
atlassian-cli jira issue search \
  --jql "project = DEV AND status = 'In Progress'" \
  --format json | jq -r '.[] | [.key, .fields.summary] | @tsv'

# Count open bugs grouped by priority
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug AND resolution = Unresolved" \
  --format json | jq 'group_by(.fields.priority.name)
    | map({priority: .[0].fields.priority.name, count: length})'

やり方はいつも同じです。絞り込みは JQL にサーバー側でやらせ、CLI にきれいな JSON を出させ、最後の仕上げを jq に任せます。これはシェルのほかの道具とも自在に組み合わせられます。課題キーを while read のループに流して 1 件ずつ処理してもよいですし、wc -l に流して件数を数えるだけでも構いません。Jira に対してより API に近い作業をしたい場合は、対になる記事のコマンドラインから Jira API を呼び出すが先へ進みます。

JQL の結果を CSV に出力する

技術者でない関係者にデータを渡す必要があるなら、答えは CSV です。--format csv と --output を組み合わせれば、Excel や Google Sheets でそのまま開けるファイルができます。

# Export a filtered set to CSV
atlassian-cli jira issue search \
  --jql "project = DEV AND type = Bug AND created >= -30d" \
  --format csv --output recent-bugs.csv

jira issue search は対話的なクエリや、ほどほどの件数の結果に向いています。プロジェクト全体や非常に大きな JQL の結果を取り出したいときは、代わりに jira bulk export を使ってください。ページネーションを自動で処理し、結果全体を JSON か CSV の 1 つのファイルに書き出します。

# Full export of a project, paginated automatically
atlassian-cli jira bulk export \
  --jql "project = DEV" \
  --output issues.json --format json

JSON でのエクスポートは課題の構造をそのまま保ちます。CSV はデータを行と列に平坦化し、表計算での分析に向きます。エクスポートを定期レポートにつなげたい場合は、Jira スプリントレポートのランブックが、クエリをスケジュール実行の共有可能なサマリーに仕立てる方法を示しています。

よく使う JQL クエリを保存する

ここからが、単発のコマンドを本当のワークフローに変える部分です。Jira の Web UI なら、サーバー上に保存済みフィルターを作るところです。atlassian-cli は JQL を直接実行するので、あらかじめ作っておくものはありません。クエリはただのテキストで、シェルから届く場所ならどこにでも保存できます。つまり「フィルター」が Web のメニューの奥ではなく、ほかのツールと並んでバージョン管理の中に置かれるということです。

いつも打つクエリはシェルのエイリアスに

毎朝実行する検索は、~/.zshrc か ~/.bashrc にエイリアスとして置いておきます。

# In ~/.zshrc or ~/.bashrc
alias my-open='atlassian-cli jira issue search --jql "assignee = currentUser() AND resolution = Unresolved ORDER BY updated DESC"'

alias sprint-bugs='atlassian-cli jira issue search --jql "project = DEV AND type = Bug AND sprint in openSprints()"'

これで my-open は自分の未完了の作業を、sprint-bugs は現在のスプリントのバグを、打ち込みなしで一覧してくれます。

引数を取るクエリはシェル関数に

プロジェクトや担当者によって内容が変わるクエリでは、固定のエイリアスより小さな関数のほうが優れています。

# Open issues for any project you name: `open-in DEV`
open-in() {
  atlassian-cli jira issue search \
    --jql "project = $1 AND resolution = Unresolved ORDER BY updated DESC" \
    --limit 50
}

git にコミットできるスクリプトに

1 行を超えるものは、チームのほかのツールの隣にスクリプトとして置いておきます。次の例は週次のトリアージ用リストを CSV に書き出すもので、cron からのスケジュール実行にも使えます。

#!/bin/bash
# triage-export.sh -- unassigned bugs from the last week, to CSV
set -euo pipefail

atlassian-cli jira issue search \
  --profile prod \
  --jql "project = DEV AND type = Bug AND assignee is EMPTY AND created >= -7d" \
  --format csv \
  --output "triage-$(date +%F).csv"

echo "Wrote triage-$(date +%F).csv"

クエリの文字列がプレーンテキストでバージョン管理されているため、チームの誰もが何に一致するのかを正確に読み取れますし、変更をプルリクエストでレビューできますし、正しい保存済みフィルターを Jira の中から探し回らずに再利用できます。このレビューのしやすさが、JQL を Web UI ではなくファイルに置いておく実務上の利点です。

Atlassian の acli との違い

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian が提供する公式 CLI（acli）ではなく、Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。ベンダーによる一次サポートが必要であれば公式の acli を、上で示した JQL、出力整形、エクスポートの挙動を備えつつ Jira、Confluence、Bitbucket、JSM を横断する単一の無料バイナリが欲しい場合は atlassian-cli を使ってください。どちらも同じ Atlassian Cloud の API を呼び出すので、書いた JQL は両者のあいだで持ち運べます。

よくある質問

関連リソース