jira

Jira スキル

概要

このスキルでは、一般的な Jira REST API ワークフローに対応する Python CLI を提供します。

• JQL で検索
• 課題の詳細を取得
• JSON ペイロードで課題を作成・更新
• 名前または ID で課題を遷移
• コメントを追加し、既存のコメントを一覧表示
• 課題タイプと作成時に必須のフィールドを確認

このスキルは、メールアドレスと API トークンによる認証を使用する Jira Cloud と、個人用アクセストークンを使用する Jira Server または Data Center に対応しています。

出力を簡潔に保つため、読み取りコマンドではデフォルトで --fields を使用してください。このスクリプトは fields.status.name のようなドット記法に対応しており、リストはタブ区切りで出力します。

前提条件

スクリプトを実行する前に、必要な環境変数を設定してください。

プラットフォーム	ランタイム
クロスプラットフォーム	Python 3.11+

認証用の環境変数

変数	必要な場合	用途
JIRA_BASE_URL	常に	Jira のベース URL。例：https://company.atlassian.net
JIRA_USER_EMAIL	Jira Cloud	Basic 認証に使用するアカウントのメールアドレス
JIRA_API_TOKEN	Jira Cloud	Jira Cloud のメールアドレスと組み合わせる API トークン
JIRA_PAT	Jira Server または Data Center	Bearer 認証に使用する個人用アクセストークン
JIRA_CLOUD_TOKEN_MODE	Jira Cloud では任意	unscoped（デフォルト）または scoped
JIRA_CLOUD_ID	スコープ付き Jira Cloud トークン	Atlassian Cloud リソース識別子

認証方式は自動的に選択されます。

• JIRA_PAT が設定されている場合、スクリプトは Jira Server または Data Center の Bearer 認証を使用します。
• それ以外の場合、スクリプトは Jira Cloud 用に JIRA_USER_EMAIL と JIRA_API_TOKEN を要求します。
• スコープ付き Cloud モードでは、リクエスト先は https://api.atlassian.com/ex/jira/{cloudId} のみに限定されます。 Cloud と Data Center の認証情報が混在している場合は、フェイルクローズします。

スコープ付き Cloud トークンの設定

スコープ付きモードでは、スコープなしモードと同じ Basic 認証用の環境変数を使用し、Cloud ID を追加します。これは OAuth 3LO フローではないため、これらの認証情報では oauth/token/accessible-resources エンドポイントは検出やイントロスペクションの手順として使用しません。

1. Atlassian アカウント用のスコープ付き API トークンを作成し、作成時にスコープを選択します。Atlassian アカウントの API トークンを管理するを参照してください。
2. 実行するコマンドに必要なスコープを選択します。read:jira-work は search、get、comments、fields を対象とします。create、update、transition、comment には write:jira-work を追加してください。細かいスコープについては、OAuth 2.0 および Forge アプリ向けの Jira スコープに記載されています。Jira のプロジェクト権限は、トークンのスコープとは別に適用されます。
3. 信頼できる Atlassian 管理者、またはサイトのアカウントレコードからサイトの Cloud ID を取得します。Cloud ID は秘密情報ではありませんが、リクエスト先を決定します。
4. Cloud ID が JIRA_BASE_URL と同じサイトのものであることを確認します。CLI ではこの関連付けを検証できません。スコープ付きモードでは Atlassian リソース API にリクエストを送信し、JIRA_BASE_URL をリクエスト先として使用しないためです。この関連付けは、運用担当者が管理する設定として扱ってください。
5. 変数を設定し、読み取り専用コマンドでアクセスを確認します。

export JIRA_BASE_URL="https://company.atlassian.net"
export JIRA_USER_EMAIL="[email protected]"
export JIRA_API_TOKEN="$(cat ~/.secrets/jira-token)"
export JIRA_CLOUD_TOKEN_MODE="scoped"
export JIRA_CLOUD_ID="your-cloud-id"
python scripts/jira.py --fields key search "ORDER BY created DESC" --max-results 1

読み取りが成功すれば、トークンとルートが連携して機能していることを確認できます。ただし、Cloud ID が JIRA_BASE_URL に対応していることの証明にはならないため、手順 4 で別途確認してください。

運用変数

変数	必須となる場合	用途
JIRA_AUDIT_LOG	任意	JSON Lines 形式の監査ログのパスです。設定すると、すべてのリクエストが監査されます（「監査ログ」を参照）。
JIRA_AUDIT_ACTOR	任意	記録されるアクターの識別情報を上書きします（例：CI サービスプリンシパル）。
JIRA_DEBUG	任意	継承された環境変数のみが対象です。1 に設定すると、失敗時に秘匿化されたトレースバックを出力します。秘匿化が無効になることはありません。
JIRA_ALLOW_INSECURE	任意	1 に設定すると、明示的に指定されたループバック HTTP 開発エンドポイントのみを許可します。
JIRA_CONFIRM_WRITES	任意	継承された環境変数のみが対象です。1 に設定すると、--confirm または --yes を指定せずに書き込み確認ゲートを通過できます。

監査ログ

JIRA_AUDIT_LOG が設定されている場合、スクリプトはすべての API リクエストについて、構造化された JSON Lines 形式の監査証跡を書き込みます。監査はフェイルクローズかつライトアヘッド方式です。

• リクエストの送信前に attempt レコードが書き込まれます。監査ログに書き込めない場合、操作は中止され、Jira には何も送信されません。
• リクエストの完了後に outcome レコード（success または error。失敗時は HTTP ステータスを含む）が書き込まれます。

各レコードには、UTC タイムスタンプ、actor（JIRA_AUDIT_ACTOR の値。未設定の場合は JIRA_USER_EMAIL または jira-pat）、操作、HTTP メソッド、正規化されたオリジン、認証モード、イベントが含まれます。リソースパス、Cloud ID、認証情報、認証ヘッダー、クエリ文字列は含まれません。この運用上機密性の高いファイルはアクセス制御されたパスに配置し、運用上必要な期間だけ保持してください。リクエスト後に監査が失敗した場合は、結果を変更せずに警告を出力します。

認証情報のローテーション

Atlassian Cloud API トークンの有効期間は、1 日から 365 日の範囲で選択できます。スコープ付きトークンを推奨します。JIRA_CLOUD_TOKEN_MODE=scoped および JIRA_CLOUD_ID を設定してください。 Atlassian 3LO は、トークン交換にクライアントシークレットが必要なため使用しません。 Jira Data Center では、Jira UI から有効範囲を限定した PAT を作成し、別途ローテーションしてください。CLI は PAT を発行しません。発行すると、トランザクション処理に対応し、モデルから見えない保存先がないまま、新しいシークレットを含む応答が返されるためです。

認証情報の設定

認証情報が不足、不完全、または機能していない場合に、このワークフローを実行します。検証を優先し、破壊的な変更を行わない仕組みです。現在の状態を監査して認証情報の取得方法を案内し、シークレットではない値のみを書き込みます。ユーザー自身が認証情報を入力した後に、接続を検証します。

安全境界

これらのルールは、自律性モードやユーザーからの依頼によって変更できません。

• チャットでトークンや PAT を求めたり、受け取ったり、繰り返したりしないでください。ユーザーにトークンを追加するよう指示するときは、必ず次の警告を表示してください。

  ⚠️ NEVER paste your API token or PAT into this chat.
     Tokens entered here are sent through the AI model and are not secure.
     Edit the credentials file directly in the editor instead.
  

• 認証情報の値を書き込まないでください。シークレットではない値（ベース URL、メールアドレス）は書き込めます。トークンの行は、ユーザーがエディターで置き換えるプレースホルダーです。

• 追跡対象のファイルに認証情報を書き込まないでください。~/.jira.env はユーザーのホームディレクトリ内にあり、リポジトリの外にあるため、誤ってコミットされることはありません。.vscode/mcp.json やリポジトリ内のファイルには書き込まないでください。

• 明示的なユーザーの確認なしに、シェルのプロファイルを変更しないでください。

• トークンの値やその一部（プレフィックスを含む）を表示しないでください。認証情報の変数は、設定済みか未設定かのみ報告してください。

• 環境変数の値を出力するコマンドを実行しないでください。printenv | grep -i JIRA など、絞り込んだダンプも禁止です。grep は出力する行を選択するだけで、値をマスクしません。そのため、有効なトークンが標準出力に送られ、トランスクリプトに残ります。代わりに、以下のプロトコルにある「設定済み／未設定」の確認方法を使ってください。トラブルシューティング中であっても、生の認証情報の値、リクエストヘッダー全体、詳細またはトレース付きの HTTP 出力を回答に含めないでください。

• ユーザーが接続テストを明示的に確認するまで、ネットワーク経由で何も送信しないでください。

ターミナルセッションの分離

エージェントのターミナルとユーザーのターミナルは別々のセッションであるため、一方で実行した export はもう一方には反映されません。CLI はクライアントを作成する前に、プロセス内で ~/.jira.env からサポート対象の Jira 変数を読み込みます。ファイル内のすべての値をデータとして扱い、シェルコードとして実行することはありません。また、ターミナルからすでに継承されている変数を上書きすることもありません。

JIRA_DEBUG と JIRA_CONFIRM_WRITES は、継承された環境変数でのみ機能する制御変数です。未確認の書き込みは、認証情報ファイルを読み込む前に拒否されるため、そのファイルによって変更権限が付与されることはありません。

POSIX プラットフォームでは、CLI はファイルの所有者が現在のユーザーであり、そのユーザーだけがアクセスできることを確認します。シンボリックリンクをたどらず、ノンブロッキングモードでパスを開いた後、値を読み込む前に、通常ファイルではないファイル、サイズ超過のファイル、不正な形式の代入文、およびグループまたはその他のユーザーに権限が付与されたファイルを拒否します。Windows では、この方法で同等の所有者とモードの確認を行えないため、ユーザーのみがアクセスできる ACL でファイルを保護してください。エラーには設定上の問題が示されますが、認証情報の値は出力されません。

環境ファイルを使ってセッション間の情報を共有します。

1. POSIX では、umask 077; touch ~/.jira.env; chmod 0600 ~/.jira.env を実行して、所有者のみがアクセスできる権限でファイルを作成します。Windows では、ユーザーのプロファイル内にファイルを作成し、ユーザーのみがアクセスできる ACL を適用します。シークレットではない値と認証情報のプレースホルダーを入力します。
2. 絶対パスを解決して表示し、どのファイルを編集するのかユーザーが正確に把握できるようにします。
3. code ~/.jira.env でファイルを開きます。
4. ユーザーがプレースホルダーを置き換えて保存します。
5. Jira CLI コマンドを実行します。CLI がファイルを直接読み込むため、source コマンドは実行しないでください。

プロトコル

1. 監査。 CLI は ~/.jira.env からサポートされている値を読み込むため、継承されたプロセスだけを調べても、セットアップ全体を監査したことにはなりません。ファイルを読み取ったり表示したりせず、ファイルが存在するか確認します。継承された環境変数については、値を表示せず、既知の名前が設定済みか未設定かを分類します。

    for v in JIRA_BASE_URL JIRA_USER_EMAIL JIRA_API_TOKEN JIRA_PAT JIRA_CLOUD_TOKEN_MODE JIRA_CLOUD_ID JIRA_AUDIT_LOG JIRA_AUDIT_ACTOR; do
     if printenv "$v" >/dev/null 2>&1; then echo "$v: set"; else echo "$v: missing"; fi
   done
   

printenv は継承された環境変数が存在する場合にのみゼロを返し、出力は破棄されるため、分類によって値が漏れることはありません。監査中に変更を加えるコマンドは使いません。プロセス内でファイルを読み込んだ後も不足している環境変数は、Jira CLI の値を表示しない検証で特定します。 2. プラットフォームを特定。 JIRA_PAT が設定されている場合は、Server または Data Center です。JIRA_USER_EMAIL と JIRA_API_TOKEN が設定されている場合は、Cloud です。プラットフォームが混在している、または曖昧な場合は、推測せずにユーザーがどのプラットフォームを使っているか確認します。誤った選択をすると、不正な認証情報と見分けにくい認証エラーが発生するためです。 3. 既存の値を検証。 JIRA_BASE_URL が https:// で始まっていることを確認し、形式が不正な値があれば指摘します。特定したプラットフォームで不足している必須環境変数を特定します。 4. 取得方法を案内。 Cloud の場合は Atlassian アカウントのトークンページを、Server または Data Center の場合は各インスタンスの個人用アクセストークン設定を案内します。手順を伝え、トークン自体は決して尋ねません。 5. ファイルを書き込む。 ~/.jira.env を作成または更新し、機密情報ではない値と認証情報のプレースホルダーを記載します。また、コミットしないよう警告するコメントも含めます。 6. 接続を検証。 認証情報を保存したことをユーザーが確認した後、読み取り専用の呼び出しを 1 回実行します。CLI はプロセス内でファイルを読み込みます。401 または 403 は、認証情報が誤っているか、有効期限切れまたは取り消し済みであることを意味します。接続エラーの場合は、ベース URL が誤っています。 7. 要約。 変更した内容、未完了の内容、各環境変数の設定済みまたは未設定の状態を報告します。

完了

特定したプラットフォームのすべての必須環境変数が設定され、ベース URL の形式が正しく、読み取り専用の呼び出しが 1 回成功した場合にセットアップ完了です。それに満たない場合は、成功したと曖昧に報告せず、残っている具体的な手順を示して未完了と報告します。

クイックスタート

現在の Jira 課題を検索し、簡潔な表で返します。

python scripts/jira.py --fields key,fields.summary,fields.status.name search 'assignee = currentUser() ORDER BY updated DESC'

簡潔なフィールドリストで 1 件の課題を確認します。

python scripts/jira.py --fields key,fields.summary,fields.status.name,fields.assignee.displayName get PROJ-123

標準入力からパイプで渡した JSON を使って課題を作成します。

cat <<'EOF' | python scripts/jira.py create
{
  "fields": {
    "project": { "key": "PROJ" },
    "summary": "Fix login timeout on mobile",
    "issuetype": { "name": "Bug" }
  }
}
EOF

パラメーターのリファレンス

コマンドまたはオプション	構文	デフォルト	説明
search	python scripts/jira.py search '<jql>' [max_results]	max_results = 50	JQL で課題を検索します
get	python scripts/jira.py get <ISSUE-KEY>	なし	1 件の課題を取得します
create	python scripts/jira.py create '<json>'	省略時は標準入力を読み込みます	JSON から課題を作成します
update	python scripts/jira.py update <ISSUE-KEY> '<json>'	省略時は標準入力を読み込みます	JSON から課題を更新します
transition	python scripts/jira.py transition <ISSUE-KEY> '<name-or-id>'	なし	課題を別のワークフロー状態に移動します
comment	python scripts/jira.py comment <ISSUE-KEY> '<body>'	省略時は標準入力を読み込みます	課題にコメントを追加します
comments	python scripts/jira.py comments <ISSUE-KEY> [ISSUE-KEY ...]	なし	1 件以上の課題のコメントを一覧表示します
fields	python scripts/jira.py fields <PROJECT-KEY> [issue-type-id]	なし	課題タイプまたは必須の作成フィールドを確認します
--fields	--fields key,fields.summary,...	なし	search、get、comments の出力から選択したフィールドを抽出します

スクリプトのリファレンス

課題を検索する

Jira Cloud のクエリには、範囲を限定した JQL を使用してください。単独の ORDER BY クエリではなく、プロジェクト、担当者、スプリントなどのフィルターを含めてください。 このスキルで想定されているクエリパターンについては、JQL リファレンスを参照してください。

python scripts/jira.py --fields key,fields.summary,fields.status.name search 'project = PROJ AND status = "In Progress"'
python scripts/jira.py --fields key,fields.summary search 'assignee = currentUser() ORDER BY updated DESC' 10

1 件の課題を取得する

python scripts/jira.py --fields key,fields.summary,fields.priority.name,fields.status.name get PROJ-123

課題を作成する

まず、有効な課題タイプを確認します。

python scripts/jira.py fields PROJ

1 つの課題タイプの必須フィールドを確認します。

python scripts/jira.py fields PROJ 10045

課題を作成します。

python scripts/jira.py create '{
  "fields": {
    "project": { "key": "PROJ" },
    "summary": "Document rollout checklist",
    "issuetype": { "name": "Task" },
    "labels": ["docs", "release"]
  }
}'

課題を更新する

python scripts/jira.py update PROJ-123 '{
  "fields": {
    "summary": "Updated summary",
    "priority": { "name": "High" },
    "labels": ["backend", "urgent"]
  }
}'

課題を遷移させる

遷移の表示名または数値の遷移 ID を使用します。

python scripts/jira.py transition PROJ-123 'In Progress'
python scripts/jira.py transition PROJ-123 31

遷移名が見つからない場合、スクリプトはエラー出力に利用可能な遷移名を返します。

課題にコメントする

python scripts/jira.py comment PROJ-123 'PR #42 addresses this issue.'
printf 'Deployed to staging.\n' | python scripts/jira.py comment PROJ-123

コメントを一覧表示する

python scripts/jira.py --fields _issue,author.displayName,created,body comments PROJ-123 PROJ-456

トラブルシューティング

症状	考えられる原因	解決方法
JIRA_BASE_URL is not set	ベース URL が設定されていません	現在のシェルで JIRA_BASE_URL をエクスポートしてください
認証エラー	トークンが間違っているか、認証変数が不足しています	Jira Server または Data Center の場合は JIRA_PAT を、Jira Cloud の場合は JIRA_USER_EMAIL と JIRA_API_TOKEN を確認してください
Invalid issue key	課題キーの形式が不正です	PROJ-123 の形式のキーを使用してください
トランジションが見つかりません	要求されたワークフローのトランジションを利用できません	エラー出力に表示されたトランジション名を指定して、コマンドを再実行してください
JSON ペイロードエラー	create または update に無効な JSON が渡されました	ペイロードを検証し、正しい形式の JSON で再試行してください
ネットワーク接続エラー	Jira インスタンスの URL に到達できません	ベース URL とローカルネットワークへのアクセスを確認してください