Jiraの「これやりたい…」をAtlassian Forgeで実現してみる - 弁護士ドットコム株式会社 Creators’ blog

この記事は、弁護士ドットコム Advent Calendar 2025 の 17 日目の記事です。

1. はじめに

クラウドサイン Product Engineering 部で主にフロントエンドエンジニアとして活動している山下（@kirehashi_3）です。

クラウドサインでは Issue の管理ツールとして Jira を使っています。
しかし、Jira を使っていると「この操作、自動化できたらもっとスムーズになるのに」といった不満を感じることが少なくありません。

例えば私たちのチームでは、ユーザーストーリーとそれに紐づく子 Issue が優先順位上でばらばらになってしまう問題がありました。
ユーザーストーリーを Backlog 上で移動しても、その配下の Issue が順位を追従してくれないため、親ストーリーだけ上に移動し子 Issue は下のままになっていまいます。これにより Backlog 上の並びがばらばらになり本来スプリント内で対応したい Issue が漏れてしまう可能性があります。

ユーザーストーリーの移動時に子イシューと優先順位が離れてしまう

「この問題の解決を Jira 上で自動化できないだろうか？」と思ったことがきっかけで、Atlassian Forge を使って自作プラグインを作ってみました。

この記事では、この経験をベースとして Atlassian Forge を触ったことがない方に向けて、

Forge がどんな仕組みで、何ができるのか
どうやってアプリを作るのか
実際に作ったプラグインの例

を紹介します。

2. Atlassian Forge とその特徴

Atlassian Forge は、Jira や Confluence を拡張するためのクラウド上のアプリ開発プラットフォームです。

Atlassian のクラウド上で Jira は動作するため、サーバーの用意が不要かつ API などに必要な認証やセキュリティも Forge が面倒を見てくれます。

特徴1：Jira の画面に UI を追加できる

Forge の特徴のひとつは、本来の Jira の UI に「拡張ポイント（extension point）」として
自分の UI を差し込める点です。

拡張ポイントの例をあげていくと

拡張ポイント	拡張される場所	利用例
`jira:issuePanel`	Issue 詳細画面のパネル	関連タスク・外部サービス情報を表示
`jira:issueAction`	課題画面のアクションメニューにボタンを追加	「Slack 通知を送る」「関連タスクを作成」など
`jira:boardAction`	Board 画面のアクションメニューにボタンを追加	一覧の内容のCSV出力など
`jira:customField`	Issue に専用のカスタムフィールドを追加	RICEスコアの表示など

といった多様な拡張ポイントがあります。今回作ったプラグインでは jira:issueAction を使用し、 Issue のアクションメニューに「優先順位を揃える」ボタンを追加しています。

また UI Kit という Forge において使いやすいように用意されたコンポーネントライブラリが用意されています。これを使うことで既存の Jira の画面と同じような見た目の UI を手軽に使うことができます。

特徴2：Jira REST API を簡単に呼べる

Forge 経由で Jira の REST API を呼び出すこともできます。 Jira には Issue の取得・更新が可能なJira REST API、Board や Backlog などアジャイルに関する機能の操作が可能なAgile APIを始めとした多様な API が用意されています。

今回のアプリでは Jira REST API からの Issue 情報の取得や Agile API からの優先順位の並べ替えを使って「ユーザーストーリーの位置に子 Issue を追従させる」処理を実現しました。

3. 実際に作ったプラグイン

今回作ったのは、前述したとおりユーザーストーリー配下の子 Issue の優先順位を自動で揃えるプラグインです。

解決したかった問題

Backlog 上でユーザーストーリーを移動しても、子 Issue が追従しないために順位がバラバラになるという問題がありました。

これを毎回手で並べ替えるのは意外と手間で移動が漏れてしまいがちでした。そこで「一括で関連する Issue の優先順位を揃えるボタン」があれば便利だと考えました。

使用した拡張ポイント

今回利用した拡張ポイントは jira:issueAction です。

jira:issueAction は Issue 画面の「•••」アクションメニューにボタンを追加でき、そこから並べ替え処理を実行します。

Forge内で実行している処理

内部では次のような流れで実装しています。

ユーザーストーリーの Issue に紐づいた子 Issue を GET /rest/api/3/issue/{issueKey} から取得
子 Issue に対して PUT /rest/agile/1.0/issue/rank でユーザーストーリーの直下に優先順位を変更

Jira上での実際のプラグインの動作

Issueのアクションメニューからプラグインを実行することで優先順位の並び替えが実行されます

4. Forge アプリの開発フロー

Forge アプリの開発は、フロントエンド開発を経験した方なら比較的簡単に進めることができます。

1. Forge CLI のインストール

$ npm install -g @forge/cli

Forge CLIを利用することでプロジェクト生成、デプロイ、権限設定まで CLI で完結させることが可能です。

2. テンプレートからアプリを生成

$ forge create

によってテンプレートから対話的にアプリを生成できます。
今回作ったような Issue 画面のアクションメニューを拡張していく場合は

? Select an Atlassian app or platform tool: Jira
? Select a category: UI Kit
? Select a template: jira-issue-action

と選択していくことでベースとなる拡張ポイント jira:issueAction のサンプルプロジェクトが生成されます。

3. UI と処理を書く

ロジックについては UI 部分と API の呼び出し部分について簡単に触れていきます。

UIの記述

UI は生成された src/frontend/index.jsx を拡張して記述します。 UI Kit のコンポーネントを使えば、スタイル調整なしで Jira 標準の見た目の UI を作ることができます。

// src/frontend/index.jsx

const App = () => {
    // ロジックは省略
    return (
        <Stack space="space.200">
            <Text>ストーリーのリンクされた作業項目が「分割」に設定されたIssueのバックログ上の並び順をストーリーの直下に移動します</Text>
            <!-- 細かいコンポーネントのロジックは省略 -->
            <LoadingButton isLoading={loading} onClick={onClick} appearance="primary">
                子Issueの並び順を移動する
            </LoadingButton>
        </Stack>
    );
};

Forge bridge APIによるAPI取得処理の呼び出し

API の呼び出し処理は jsx コンポーネント内に書くことができません。よって、Forge bridge APIを利用して、 src/resolvers/index.js に記述した処理をテンプレートから呼び出す必要があります。

// src/resolvers/index.js

resolver.define('reorderSplitUnderStory', async ({ payload }) => {
    // ここにAPIの呼び出し処理を書いていく
});

export const handler = resolver.getDefinitions();

// src/frontend/index.jsx

const App = () => {
    const onClick = async() => {
        // issueKeyの取得処理などは省略
        // index.jsで定義したresolverをinvokeで呼び出す
        const res = await invoke('reorderSplitUnderStory', { issueKey });
    }
    return (
        <Stack space="space.200">
            <Text>ストーリーのリンクされた作業項目が「分割」に設定されたIssueのバックログ上の並び順をストーリーの直下に移動します</Text>
            <!-- 細かいコンポーネントのロジックは省略 -->
            <LoadingButton isLoading={loading} onClick={onClick} appearance="primary">
                子Issueの並び順を移動する
            </LoadingButton>
        </Stack>
    );
};

APIの呼び出しロジック

API の呼び出しロジックは src/resolvers/index.js の resolver 内に記述します。 api.asApp().requestJira() で Jira の REST API を呼び出します。

// src/resolvers/index.js

resolver.define('reorderSplitUnderStory', async ({ payload }) => {
    ...
    await api.asApp().requestJira(
        route`/rest/agile/1.0/issue/rank`, {
            method: 'PUT',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ issues: [childIssueList], rankAfterIssue: storyIssueKey }),
        }
    );
});

export const handler = resolver.getDefinitions();

4. Jira にデプロイ・インストールする

$ forge deploy

により Atlassian へデプロイされます。その先は Atlassian Developer Console にてデプロイした Forge App の管理ができるようになります。後述しますが導入には管理者権限が必要となります。よって、Developer Console の Distribution タブにて一時的に配布用 URL を発行して管理者にインストールしてもらうのが導入しやすいです。

5. 実際に社内で導入する際の注意点

導入に管理者権限が必要

Forge アプリは、Jira の管理者権限を持ったユーザーのみがインストールできます。よって、導入する際は情シスなど Jira を管理しているチームとの連携が必要となります。ただし初回のインストール後は新たな権限要求を追加しない限り、アップデートは管理者権限不要で適用されます。

従量課金である

無料枠は非常に大きいのですが従量課金である点については注意してください。特に利用枠は forge アプリごとに算出されるため複数のプロジェクトにアプリを導入した場合はそれらが合算された状態で金額が算出されることになります（課金形態の公式資料）。ちなみに今回作成したプラグインは、現状では無料枠上限の 1/1000 程度に収まっています。

6. Forge を触ってみて感じたこと

良かった点

まずは Atlassian 公式の機能であるため、Jira の UI に対して自然に拡張できる点が優れています。また API 呼び出しに関してアクセストークンの管理などが不要なため開発・保守がしやすい点についても単に API を呼び出す外部ツールでは実現できない利点です。

困った点

Forge に関する公式ドキュメントは潤沢ですが、API に関するドキュメントなどがさまざまなページに散らばっていて情報を探しづらいです。また拡張ポイントとして定義された場所にしか追加ができないため拡張の自由度では劣ります。例えば Backlog でチェックを入れた Issue に独自の一括操作を追加したり、Board の列に追加の情報を表示したりといった拡張は現在はできません。