Jira Forge App

A Jira dashboard gadget that embeds AI-powered portfolio intelligence directly inside Jira. Powered by the Anthropic Claude API.

Idea Agent

Analyze business ideas against live Jira data, OKRs, and roadmap context

Portfolio Advisor

Ask strategic questions and get direct, opinionated answers

Velocity Insights

Surface slow tickets, overloaded assignees, and stale branches

Ticket Quality

Flag under-specified epics with missing acceptance criteria and no OKR tags

Prerequisites

Atlassian Forge CLI installed globally
Node.js 18+
An Atlassian cloud developer account
An Anthropic API key

Setup

1. Install the Forge CLI

npm install -g @forge/cli
forge login

2. Install dependencies

cd alignd-jira-forge
npm install

3. Register the app

If this is a fresh clone, register a new Forge app:

forge register

This updates the app.id in manifest.yml with your unique app ID.

4. Deploy

forge deploy

5. Install on a Jira site

forge install

Select your Jira cloud site when prompted. The gadget will be available in the dashboard gadget picker.

6. Configure settings

After adding the gadget to a Jira dashboard:

Click the Settings button in the top-right of the gadget
Enter your Anthropic API key — stored securely in Forge encrypted storage, never exposed to the browser
(Optional) Paste your OKR document text for organizational context
(Optional) Add a GitHub repo URL to enable code health signals

Local Development

Use forge tunnel to run the app locally while testing against your Jira cloud site:

forge tunnel

This proxies resolver functions through your local machine so you can iterate without redeploying.

Architecture

alignd-jira-forge/ ├── manifest.yml # Forge app manifest (modules, permissions) ├── package.json # Dependencies ├── src/ │ ├── frontend/ │ │ └── index.jsx # React UI (Forge Custom UI with @forge/react) │ └── resolvers/ │ └── index.js # Backend resolver functions (Jira API + Claude API) └── static/ └── thumbnail.png # Gadget thumbnail

Data Flow

1 Frontend calls invoke('analyzeIdea', { idea }) via @forge/bridge

2 Resolver fetches live Jira data (epics, sprints, blocked issues) via @forge/api

3 Resolver builds a system prompt with real Jira context + OKRs

4 Resolver calls Claude API server-side (API key never leaves the backend)

5 Structured JSON response is returned to the frontend for display

Jira APIs Used

Endpoint	Purpose
`GET /rest/api/3/search?jql=issuetype=Epic`	Fetch project epics
`GET /rest/api/3/search?jql=status=Blocked`	Fetch blocked issues
`GET /rest/agile/1.0/board/{id}/sprint?state=active`	Get active sprint

Permissions

read:jira-work — Read issues, epics, sprints
read:jira-user — Read assignee info for team load analysis
External fetch: https://api.anthropic.com — Claude API calls from backend only

Security

The Anthropic API key is stored in Forge encrypted storage (storage.setSecret)
API calls to Anthropic happen server-side only — the key is never sent to or accessible from the frontend
The app only requests read permissions — it never modifies Jira data