こんにちは。アジャイルコーチとして、これまで数多のチームが「Jiraの沼」に沈んでいく姿を見てきました。
「Jiraのカスタムフィールドを増やしすぎて、画面が重いし、管理も破綻した」
「外部システムとの連携用に、わざわざ別のDBを立てて同期させている」
そんな嘆きを聞くたびに、私はこう答えます。「Jiraの中に、Jiraの外側の世界を閉じ込める『隠し扉』があることを忘れていませんか？」
今日は、Jiraの裏側に眠る強力な武器、「Entity Properties（エンティティプロパティ）」についてお話しします。これは、Jiraのデータベースを拡張する極めてマニアック、かつ最高にクールな裏技です。
—
1. Entity Propertiesとは何か？：Jiraの「隠しポケット」
Entity Propertiesとは、Jiraの課題（Issue）やプロジェクト、ユーザーに対して、JSON形式で任意のメタデータを直接保存できる機能です。
通常、Jiraのカスタムフィールドは定義した瞬間にデータベースのスキーマを占有し、レポートや検索の負荷になります。しかし、Entity Propertiesは違います。REST API経由でのみ読み書き可能な「第2のデータ領域」であり、UIに表示されない「裏側の設定値」を置くのに最適なのです。
なぜこれを使うのか？
- 外部連携のキャッシュ: 外部システム（GitHubのプルリクIDや外部のCIビルド結果など）を、Jira側で保持する。
- フラグ管理: 複雑な条件分岐のための「実行状態」や「隠しオプション」を管理する。
- スキーマレスの自由: フィールド定義をいちいち管理者に依頼しなくても、開発者がAPIから自由に構造を変更できる。
—
2. さあ、試してみよう：Hello World的なデータ挿入
今回はJiraのREST APIを使って、ある課題に対して「外部システムのステータス」というメタデータを埋め込んでみます。
ステップ1：APIトークンの準備
[Atlassianの管理画面](https://id.atlassian.com/manage-profile/security/api-tokens)からAPIトークンを発行してください。これがあなたの「鍵」になります。
ステップ2：APIでプロパティを書き込む
以下のコマンドは、課題キー `PROJ-123` に対して `external_metadata` というキーでJSONを保存する例です。
Jira APIのエンドポイント設定
JIRA_URL=”https://your-domain.atlassian.net”
ISSUE_KEY=”PROJ-123″
EMAIL=”your-email@example.com”
API_TOKEN=”your-api-token”
プロパティを保存 (PUT)
curl -X PUT “${JIRA_URL}/rest/api/3/issue/${ISSUE_KEY}/properties/external_metadata” \
-u “${EMAIL}:${API_TOKEN}” \
-H “Accept: application/json” \
-H “Content-Type: application/json” \
-d ‘{
“status”: “sync-complete”,
“external_id”: “GH-9988”,
“last_synced”: “2023-10-27T10:00:00Z”
}’
ステップ3：正しく保存されたか確認する
保存したデータは以下のGETコマンドでいつでも呼び出せます。
curl -X GET “${JIRA_URL}/rest/api/3/issue/${ISSUE_KEY}/properties/external_metadata” \
-u “${EMAIL}:${API_TOKEN}”
これだけで、Jiraの課題に「隠された属性」が付与されました。画面を汚すことなく、アプリケーションが参照するためのデータがそこに存在しています。
—
3. 現場で震えるほど役立つ「極意」
この機能を使いこなすと、開発チームのベロシティは劇的に変わります。以下の活用例を参考にしてみてください。
① 外部システムの同期管理（サイロ化の防止）
CI/CDパイプラインからビルド結果をこのプロパティに書き込むようにすれば、Jiraのカスタムフィールドを汚染することなく、課題の詳細画面に「最新のビルド状況」を表示するUI（Forgeアプリやブラウザ拡張機能）を自作できます。
② 「一時的なフラグ」としての活用
「特定の条件を満たしたときだけ、自動化スクリプトがフラグを立てる」といった処理を、Jiraのワークフローに依存せずに実装可能です。ワークフローが巨大化するのを防ぐ「軽量な状態管理」として機能します。
—
先輩エンジニアからのアドバイス
このテクニックの最大の利点は、「Jiraの標準機能を破壊せずに、自分たちの開発プロセスに必要な情報を拡張できる」という点にあります。
しかし、注意点もひとつ。「プロパティに入れすぎないこと」です。ここに入れたデータは、デフォルトのJQL（Jira Query Language）からは直接検索できません（※Jira Premiumの機能やプラグインを使えば検索可能ですが、基本はAPIアクセス前提です）。
「検索する必要はないが、プログラムから常に参照したいデータ」をここに逃がす。これが、Jiraを「単なるタスク管理ツール」から「自律駆動する開発プラットフォーム」へと進化させる第一歩です。
明日から、皆さんのJiraの課題に、何かひとつ「隠しデータ」を仕込んでみてください。ツールが単なる管理表ではなく、あなたたちのチームの意図を汲み取る「相棒」に変わるはずです。
もし実装で詰まったら、いつでも聞いてください。コードの向こう側にある「目的」を一緒に整理しましょう。