jira

jira — ターミナルから Jira Issue Tracker を操作

REST API v3 を介して Atlassian Jira Cloud を操作します。課題の検索や詳細の表示、課題の作成、コメントの追加、検索結果の件数確認、プロジェクト一覧の取得、ステータスの遷移ができます。

セットアップ

1. id.atlassian.com/manage/api-tokens で API トークンを生成します
2. 環境変数を設定します。

export JIRA_EMAIL="[email protected]"       # Atlassian account email
export JIRA_API_TOKEN="YOUR_API_TOKEN"           # from id.atlassian.com
export JIRA_SERVER="https://your-domain.atlassian.net"

認証には base64(email:token) による HTTP Basic を使用します。メールアドレスを使用し、パスワードは使用しないでください（API でのパスワード使用は非推奨です）。Cloud には Personal Access Token はありません。Bearer PAT は Data Center 専用です。トークンの有効期限は最長 1 年です。--help と --dry-run は認証情報なしで使用できます。

基本コマンド

me / projects — アカウント情報と対象範囲

jira me                       # verify auth; your accountId, timezone
jira projects --json          # all accessible projects

list — 課題を検索

jira list                                                # recent issues
jira list --project PROJ                                 # by project
jira list --jql 'assignee=currentuser() AND status=Open' # custom JQL
jira list --project PROJ --max 120 --json                # >50 auto-pages via startAt offsets

view — 課題の詳細

jira view PROJ-123                        # summary, status, assignee, description
jira view PROJ-123 --json                 # machine-readable

説明は Atlassian Document Format（ADF）で返されます。CLI は表示用にプレーンテキストを抽出します。

count — 検索結果の件数をすばやく確認

jira count --jql 'issuetype = Bug AND resolution = Unresolved'   # {"count": N}

POST /search/approximate-count を使用し、行を取得しません。JQL 自体には COUNT や集計機能はありません。

create — 課題を新規作成

jira --yes create --project PROJ --summary "Fix login bug"            # Task (default)
jira --yes create --project PROJ --summary "Crash on startup" --type Bug
jira --yes create --project PROJ --summary "Add dark mode" --type Story --priority High
jira create --project PROJ --summary "Test" --dry-run           # preview payload

説明は ADF ドキュメントとして送信されます。プレーンな段落を超えるリッチフォーマットには、raw ADF JSON が必要です。references/rest-issues-and-transitions.md を参照してください。

comment — スレッドにコメントを追加

jira --yes comment PROJ-123 -m "Fixed in latest build"
jira comment PROJ-123 -m "Looking into it" --dry-run

transitions + transition — ステータスを変更

jira transitions PROJ-123                     # LIST valid transition IDs first
jira --yes transition PROJ-123 --to "In Progress"   # then apply by name or ID
jira --yes transition PROJ-123 --to Done --resolution Done
jira transition PROJ-123 --to "In Review" --dry-run

不明な場合は、必ず最初に transitions を実行してください。ID はワークフローと現在のステータスによって異なり、ワークフロー間で同じ名前が使われることもあります。--resolution を指定すると、完了時に解決状況を求める画面に対応できます。省略すると、不足しているフィールド名を含むエラーとともに 400 が返されます。

グローバルフラグ

すべてのフラグはどの位置でも使用できます。読み取りコマンドには認証情報が必要ですが、--help と --dry-run には必要ありません。変更を行うコマンドでは、明示的に --yes または --force を指定する必要があります。

jira --json list --project PROJ                        # machine output anywhere
jira --dry-run create --project PROJ --summary "Test"  # offline preview
jira --yes create --project PROJ --summary "Test"      # explicit write authorization
jira --quiet list                                      # suppress non-essential output

--json はコマンドごとに 1 つの JSON オブジェクトを標準出力に出力します。jq にパイプして構造化データを扱えます。

複数ステップのパイプラインレシピ

スプリントの整理

停滞しているスプリント作業を見つけ、各チケットを確認して、完了したものをクローズします。

jira list --jql 'sprint IN openSprints() AND updated < -14d AND resolution = Unresolved' --json \
  | jq -r '.issues[].key' \
  | while read -r key; do jira view "$key"; jira transitions "$key"; done
# after human review, per key:
jira --yes transition "$key" --to Done --resolution Done

list --json の形式は {"total": N, "issues": [{"key", "summary", "status", "assignee", "issuetype", "priority"}]} です。

安全に対象を確認して一括クローズ

遷移 ID はワークフローごとに異なるため、変更を行う前に確認してください。

for key in $(jira list --jql 'status = "In Progress" AND updated < -30d' --json | jq -r '.issues[].key'); do
  tid=$(jira transitions "$key" --json | jq -r '.transitions[] | select(.status_category=="completed") | .id' | head -1)
  [ -n "$tid" ] && jira --yes transition "$key" --to "$tid" --resolution Done
done

jq を使った週次ダイジェスト

jira list --jql 'assignee = currentUser() AND updated >= startOfWeek()' --max 50 --json \
  | jq -r '.issues[] | "\(.key)\t\(.status)\t\(.summary)"'

すぐに実行できるクエリは、役割ごとに整理された references/jql-cookbook.md にも掲載されています。

jq で --json を使用する

jira list --project PROJ --json | jq '.issues[] | {key, status, assignee}'
jira count --jql 'project = PROJ' --json | jq .count
jira transitions PROJ-123 --json | jq -r '.transitions[] | "\(.id)=\(.name) -> \(.to_status)"'

既知の注意点

• 検索エンドポイントの二重性 — この CLI は、オフセットページネーション（startAt、maxResults、total）を使用する従来の /rest/api/3/search を使用します。Atlassian の拡張版 /rest/api/3/search/jql はこれを置き換え、不透明な nextPageToken（および isLast）を使用します。startAt と total はなく、デフォルトでは ID のみがフィールドに含まれ、上限のない JQL は拒否されます（order by key desc のみの場合は 400）。従来のエンドポイントは非推奨であり（「現在削除中」として 2024 年 10 月に発表、2025 年 5 月 1 日以降に削除予定）、移行を強制されることが予想されます。2 つのページネーション方式を混在させると、従来型の「1 ページ目を無限に繰り返す」ループが発生しがちです。
• ページネーションの上限 — 従来のページでは、デフォルトで maxResults=50 です。ページをまたいで total が減ることがあるため、古い total を信用せず、空のページも許容してください。
• トランジションの前に GET が必要 — トランジション ID（"31"、"711"）は特定のワークフロー／ステータスに属します。無効な ID を指定してもエラーではなく、空のリストが返ります。「完了」系の画面では resolution が必須になることがよくあります。必須フィールドが欠けている場合は、該当フィールドを示す "errors": {"resolution": "..."} を含む 400 が返されます。
• すべての箇所で ADF — v3 のペイロードでは、説明、コメント、環境フィールドに ADF JSON オブジェクトが必要です。文字列だけを渡すと拒否されます。
• 認証にはメールアドレスと API トークンを使った HTTP Basic を使用します。CAPTCHA によるロックアウト（ログイン失敗の繰り返し）が発生すると、REST 認証が全面的にブロックされます。症状を示すヘッダーは X-Seraph-LoginReason: AUTHENTICATION_DENIED です。再試行せず、ブラウザーで解決してください。
• レート制限では、Retry-After と RateLimit-Reason ヘッダーとともに 429 が返されます。CLI は両方を表示しますが、自動再試行はしません。また、書き込みは課題ごとに約 2 秒あたり 20 件までに制限されます。
• プロジェクトキーでは、大文字と小文字が区別されるコンテキストがありますが、API は通常どちらの表記も受け付けます。
• username ではなく accountId — ユーザーフィールドでは Atlassian のアカウント ID を使用します（GDPR に伴う移行）。username は API から削除されています。

JQL の注意点

• != は空の値を除外します — assignee != currentUser() は、未割り当ての課題を暗黙のうちに除外します。(assignee != currentUser() OR assignee IS EMPTY) と記述してください。
• AND は OR より優先されます — A OR B AND C は A OR (B AND C) として解析されます。OR グループには必ず括弧を付けてください。括弧がない場合は、左から右に評価されます。
• 先頭のワイルドカードは使えません — summary ~ "*bug" は全件スキャンを強制します。ワイルドカードは先頭以外の文字の後に置いてください。
• 最初にプロジェクトで絞り込む — 大規模なインスタンスで最も効果の大きいパフォーマンス改善策です（公式の最適化ガイダンス）。
• 履歴演算子にはフィールドのホワイトリストがあります — WAS／CHANGED が機能するのは Assignee、Fix Version、Priority、Reporter、Resolution、Status のみです。履歴追跡のないフィールドでは、何も返さずに失敗します。
• 相対日付では大文字と小文字が区別されます — -1m は分、-1M は月です。日単位の式は各ユーザーのタイムゾーンで評価されます。
• JQL には集計機能がありません — COUNT／SUM は使えません。jira count（概算カウントエンドポイント）またはダッシュボードガジェットを使用してください。

使用する場面

• ターミナルからのあらゆる Jira Cloud 操作：検索、表示、作成、コメント、トランジション
• JQL クエリの作成、デバッグ、最適化 — 言語のリファレンス全体を収録
• スプリントレビュー、トリアージの一括処理、一括ステータス整理、ダッシュボード、保存済みフィルターの設計

使用しない場面

GitHub または GitLab の課題追跡には、このスキルを使用しないでください（gh など、各プラットフォーム専用のツールを使用してください）。権限スキームやワークフロー編集などの Jira サイト管理（管理 UI の領域）、Confluence コンテンツ、または Jira API を使ったサーバー側インテグレーションの構築にも使用しないでください（代わりに Atlassian の公式 SDK ドキュメントを参照してください）。

参考ファイル

ファイル	トピック	読むタイミング
references/rest-auth-and-search.md	Basic 認証／トークンの仕組みと OAuth／PAT、レート制限ヘッダー、エラーエンベロープ、従来型検索と拡張検索のページネーションの違い	認証情報の設定、429／401 の処理、大規模な検索結果のページネーション、または /search からの移行
references/rest-issues-and-transitions.md	GET／POST／PUT の課題形式、画面フィールド要件を含む GET→POST のトランジションフロー、ADF ドキュメントモデル	課題のプログラムによる作成／編集、トランジションの失敗の解決、リッチテキストの書式設定
references/jql-functions-catalog.md	サポート対象のフィールド／演算子を含むすべての JQL 関数 — 日付／時刻、ユーザー、スプリント／バージョン、カスタムフィールド、JSM の承認と SLA	クエリで使用できる演算子／関数の確認
references/jql-best-practices.md	演算子の優先順位、パフォーマンスのルール、空の値に関する落とし穴、トラブルシューティングの手順、マーケットプレイス拡張機能	クエリが遅い、結果が正しくない、または AND／OR が混在している場合
references/jql-cookbook.md	役割別（開発者、スクラムマスター、PO／マネージャー、パワーユーザー、管理者）に整理された、すぐに実行できる 50 個のクエリ	フィルターや自動化ルールの作成、スプリントレビュー
references/jql-history-and-dates.md	WAS／CHANGED 述語の解説、相対日付式の表、保存済みフィルターの構成と命名規則	履歴クエリ、日付計算、再利用可能な保存済みフィルターの設計

利用可能なスクリプト

スクリプト	用途	実行方法
scripts/jira	このスキルが使用する CLI：me、list、view、projects、create、comment、count、transitions、transition — すべて --json／--dry-run に対応し、認証は遅延実行され、50 件を超える結果はオフセットページネーションで取得し、解析済みの API エラーメッセージと 429 の Retry-After を表示します。上記の Jira データに関する質問にはすべてこれを実行してください。	scripts/jira list --project PROJ --json
scripts/test_jira.py	ヘルプテキスト、引数エラー、ドライランの計画、ページネーションループ、エラーエンベロープ、トランジション解決ロジックをカバーするオフラインの pytest／unittest スイートです。ネットワーク接続は不要です。scripts/jira の変更後に実行してください。	.venv/bin/python3 -m pytest -p no:cacheprovider --strict-markers scripts/test_jira.py

前提条件

• requests を含む Python 3.8 以降（それ以外の場合は標準ライブラリを使用）。直接実行できない場合は python3 scripts/jira ... として実行してください
• ドライラン以外のコマンドには JIRA_EMAIL と JIRA_API_TOKEN をエクスポートしてください（トークンは https://id.atlassian.com/manage/api-tokens から取得）。JIRA_SERVER のデフォルト値は https://your-domain.atlassian.net です
• --json の後処理には jq の使用を推奨します

制限事項

• Jira Cloud REST v3 が対象です。Data Center サイトでは認証方法が異なり（Bearer PAT）、より古い API が公開されています
• この CLI が使用する従来の検索エンドポイントは上流で非推奨になっています。いずれ /search/jql のトークンページネーションへの強制移行が必要になる見込みです
• プレーンな段落を超えるリッチテキストの作成には、ADF JSON を手作業で構築する必要があります
• 429 の自動再試行はありません。多数の書き込みを繰り返す場合は、呼び出しの間に待機してください