Jira の課題階層とエピックを解説（CLI クエリ付き）

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

Jira の課題階層とは

Jira の課題階層とは、作業を段階的に整理する親子構造のことです。既定の Jira Cloud プロジェクトでは 3 段階あり、最上位にエピック、中間に標準の課題（ストーリー、タスク、バグ）、最下位にサブタスクが位置します。各項目は 1 つ上のレベルにあるちょうど 1 つの親にひも付くため、プロジェクト全体はエピックを根とするツリーの集合になります。

このモデルは Jira の Web UI で 1 件ずつクリックして追う分には分かりやすいものの、規模が大きくなると点検に時間がかかります。「どのエピックにまだ未完了の子課題が残っているか」「このストーリーにサブタスクは何件残っているか」といった問いに答えるなら、コマンドラインのほうがはるかに高速です。このガイドでは各レベルを平易に説明したうえで、JQL で課題階層を検索し、たどるための atlassian-cli のコマンドを具体的に示します。

Atlassian の acli との違い：atlassian-cli は、MIT ライセンスのコミュニティによる独立したオープンソースプロジェクトです。Atlassian が提供する公式 CLI（acli）ではありません。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援、保守のいずれも受けていません。ベンダーによる一次サポートが必要なら公式の acli を使ってください。Jira、Confluence、Bitbucket、Jira Service Management をまたぐ無料の Rust バイナリを 1 つで済ませたい場合や、jq のようなシェルツールにきれいにパイプしたい場合は atlassian-cli を使ってください。

上から下までの 4 つのレベル

Jira は課題階層の各レベルに整数を割り当てています。標準の課題はレベル 0、サブタスクはレベル -1（標準より下）、エピックはレベル 1（標準より上）です。Premium プランでは、Atlassian の高度な計画機能によってエピックより上にカスタムレベルを追加でき、最も一般的なのは複数のエピックを 1 つの戦略テーマにまとめるイニシアチブレベルです。全体像は次のとおりです。

この表について、実務上重要な点が 2 つあります。1 つ目は、標準の階層にはストーリーだけでなくタスクやバグも並んで存在し、いずれもレベル 0 だということです。2 つ目は、イニシアチブの行が存在するのは、追加レベルに対応したプランを使っていて、管理者がそれを設定している場合だけだということです。無料プランや Standard プランの通常のプロジェクトでは、課題階層はエピックで止まります。

CLI から各レベルを検索する

以下のクエリはいずれも、JQL 文字列を渡すだけの単純な jira issue search です。JQL 関数の standardIssueTypes() と subTaskIssueTypes() は、インスタンスがその階層に対応付けている課題タイプに解決されるため、プロジェクトが課題タイプの名前を変更しても動作し続けます。

# All epics in a project
atlassian-cli jira issue search \
  --jql "project = DEV AND issuetype = Epic" \
  --limit 100

# All standard issues (stories, tasks, bugs) - no epics, no subtasks
atlassian-cli jira issue search \
  --jql "project = DEV AND issuetype in standardIssueTypes()"

# Every subtask in the project
atlassian-cli jira issue search \
  --jql "project = DEV AND issuetype in subTaskIssueTypes()"

いずれのコマンドにも --format json を付ければ機械可読な出力が得られ、--format csv --output level.csv を付ければ結果をスプレッドシートで開けます。上記のタイプフィルターと組み合わせられる日付関数やステータスフィルターを含む、より広範な JQL のリファレンスは JQL クエリチートシートをご覧ください。

エピックから子課題をたどる

課題のレベルが分かるだけでは半分に過ぎません。より役立つのは「この特定のエピックの下には何があるのか」という問いです。その答えが JQL の parent フィールドで、任意の子から 1 つ上のレベルを指します。エピック DEV-100 の直接の子課題を一覧するには次のようにします。

# Direct children of an epic (stories, tasks, bugs)
atlassian-cli jira issue search \
  --jql "parent = DEV-100" \
  --limit 100

同じ parent フィールドは 1 つ下の階層でも使えます。ストーリー DEV-123 のサブタスクを一覧するには、parent にそのストーリーを指定します。

# Subtasks of a single story
atlassian-cli jira issue search \
  --jql "parent = DEV-123 AND issuetype in subTaskIssueTypes()"

互換性について 1 点補足します。新しい Jira Cloud のプロジェクトでは、エピックとストーリーの関係にも、ストーリーとサブタスクの関係にも、統一された parent フィールドを使います。一方、古い company-managed プロジェクトの中には、エピックとの関係を従来の Epic Link フィールドに保持しているものもあります。そうしたプロジェクトで parent = DEV-100 が何も返さない場合は、代わりにフィールド名で検索してください（シェルが内側の二重引用符を保持するよう、クオートに注意してください）。

# Classic company-managed projects: query the Epic Link field
atlassian-cli jira issue search \
  --jql '"Epic Link" = DEV-100'

単一の課題について、親、ステータス、タイプを一度に確認するには jira issue get を使います。

atlassian-cli jira issue get DEV-123 --format json | jq '{key, type: .fields.issuetype.name, parent: .fields.parent.key, status: .fields.status.name}'

jq で課題階層のツリーを作る

atlassian-cli に専用のツリーコマンドはありませんが、上記の 2 つのクエリを組み合わせれば実現できます。プロジェクト内のすべてのエピックを一覧し、各エピックキーをループしてその子課題を検索します。--format json は単純な配列を返すため、jq で必要なフィールドだけを取り出せます。

#!/bin/bash
# Print a project's epic -> child tree
set -euo pipefail
PROJECT="DEV"

atlassian-cli jira issue search \
  --jql "project = $PROJECT AND issuetype = Epic" \
  --format json | jq -r '.[].key' | while read -r EPIC; do
    echo "Epic: $EPIC"
    atlassian-cli jira issue search \
      --jql "parent = $EPIC" \
      --format json | jq -r '.[] | "  - \(.key) [\(.fields.status.name)] \(.fields.summary)"'
done

これにより、各エピックとその子課題がステータスと要約付きでインデント表示されます。ターミナルから離れずにリリース全体を見直す手軽な方法です。エピックのうちどれだけが未完了かを確認するために、子課題をステータスごとに集計することもできます。

# Count an epic's children by status
atlassian-cli jira issue search \
  --jql "parent = DEV-100" \
  --format json | jq 'group_by(.fields.status.name)
    | map({status: .[0].fields.status.name, count: length})'

スプリントごとにこうした見直しを行うのであれば、このループを定期レポートに組み込みましょう。CLI によるタスク管理のガイドでは、その場限りのクエリを繰り返し使えるワークフローに変える方法を扱っています。Jira CLI リファレンスには、課題と検索のフラグがすべてまとまっています。

各レベルの課題を作成する

課題階層を作る手順は、検索する手順のちょうど裏返しです。先に親を作り、そこに子をひも付けます。エピックは Epic タイプの課題にすぎません。

# Create an epic
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Epic \
  --summary "Checkout redesign"

子をそのエピックにひも付けるには、作成時に parent フィールド（または従来の Epic Link フィールド）を設定します。正確なフィールド ID はインスタンスによって異なるため、まず jira fields list で調べ、fieldId=value の形式を受け付ける汎用の --field フラグで渡します。

# 1. Find the field that stores the epic/parent link
atlassian-cli jira fields list --format json \
  | jq '.[] | select(.name | test("Epic|Parent"; "i")) | {id, name}'

# 2. Create a story under epic DEV-100 using the field id you found
#    (customfield id shown here is an example - use yours)
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Story \
  --summary "Cart summary widget" \
  --field 'customfield_10014="DEV-100"'

--field の仕組みは、あらゆるカスタムフィールドで使うものと同じです。ID さえ分かれば、エピックへのひも付けもスプリントもその他のカスタム値も同じ方法で設定できます。既存の課題を後からまとめたい場合は、jira issue update と同じフィールドフラグで親の関係を変更できますし、Jira CLI 完全ガイドのパターンを使えば課題を一括で移動できます。

課題階層でよくある落とし穴

課題階層に対して初めてスクリプトを書くとき、つまずきやすい点がいくつかあります。あらかじめ知っておけば、クエリが想定より少ない件数しか返さないときに悩まずに済みます。

• エピックの検索は 1 階層しか返しません。parent = DEV-100 はエピックの直接の子課題（ストーリー、タスク、バグ）を一覧し、そのサブタスクは含みません。サブタスクの親はエピックではなく自分のストーリーなので、ツリーの最下層まで届くには 2 段階必要です。まずエピックの子課題を検索し、次に各子課題のサブタスクを検索します。
• standardIssueTypes() はエピックとサブタスクを意図的に除外します。この関数はレベル 0 のタイプだけに解決されます。階層を問わずプロジェクト内のすべてを取得したい場合は、タイプフィルターを外して project = DEV だけで検索してください。
• ページサイズに注意してください。大きなエピックは、1 ページで返る件数より多くの子課題を持つことがあります。課題の多いエピックをたどるときは --limit を引き上げ、ループが黙って課題を取りこぼさないようにしてください（たとえば --limit 200）。
• parent と Epic Link の違い。team-managed プロジェクトと新しい company-managed プロジェクトは統一された parent フィールドを使いますが、古い company-managed プロジェクトの中には従来の Epic Link を使い続けているものもあります。片方が何も返さない場合は、エピックが空だと決めつける前にもう片方を試してください。
• 課題タイプ名はプロジェクトごとに異なります。プロジェクトによっては「Story」の名前が変更されていたり、独自のサブタスクタイプが追加されていたりします。再利用するスクリプトで issuetype = Story を直書きするより、関数フィルターの standardIssueTypes() と subTaskIssueTypes() のほうが安全なのはこのためです。

これらを踏まえておけば、先ほどの走査スクリプトは、整然とした無料プランのボードから、最上位にイニシアチブ階層を持つ Premium インスタンスまで、どのようなプロジェクト構成でも正しく動作します。

よくある質問

関連リソース