Jira Integration

Connect Jira to capture decisions from issues and discover historical decisions.

Features

• Issue capture - /align command in Jira issues
• Comment capture - Capture decisions from issue comments
• Discover - AI-powered scan of historical issues
• Evidence linking - Decisions link back to Jira issues

Setup (Cloud)

1. Go to Settings → Integrations in Align
2. Click Connect Jira
3. Select your Atlassian site
4. Authorize Align
5. Select which projects to include

Capturing Decisions

From Issue Comments

Add a comment with the /align command:

/align We decided to split this epic into smaller stories
for better velocity tracking.

Ambient capture

On projects you have opted in, comment activity on an issue can raise a capture suggestion without anyone typing /align. This is off by default, opts in per project, and stores nothing until a human confirms.

No react-to-capture on Jira

Atlassian Cloud emits no comment-reaction webhook events, so the 📌 / 🔖 path that works in Slack and Teams is not available here. Use /align, or opt the project into ambient suggestions.

Discover Mode

Discover scans your Jira history for decision-like content:

1. Go to Discover in Align
2. Select Jira as the source
3. Choose projects and date range
4. Review suggested decisions
5. Import the relevant ones

What Discover Looks For

• Issues with "decision" or "decided" in the content
• Architecture Decision Records (ADRs)
• Sign-off and approval comments
• Trade-off discussions
• RFC or proposal issues

Best Practices

1. Use consistent labels - Tag decision-related issues
2. Include rationale - Document the "why" in issue descriptions
3. Link related issues - Connect decisions to implementation tickets
4. Review Discover results - Not every suggestion is a decision

Permissions

Jira and Confluence share one Atlassian OAuth app, and connecting Jira requests the Confluence read scopes as well, so a single consent sets up both products. The first consent is read-only. Align asks for a write scope later, when you switch on the feature that needs it, and the consent screen names the feature. The lists below are read from services/gateway/src/auth/connectorScopeSets.ts.

Read scopes (the first connect)

Scope	Purpose
read:jira-work	Read issues and comments
read:jira-user	Map Jira users to Align users
read:page:confluence	Read Confluence page content, from the shared grant
read:space:confluence	Enumerate Confluence spaces you have granted
read:comment:confluence	Read a Confluence comment that triggered a capture
read:confluence-content.all	Discover scans across granted Confluence content
offline_access	Refresh the token without re-authorising

Write scopes, one feature at a time

Feature	Scope it adds	What Align does with it
Jira ticket creation, comments and links (jira_writes)	write:jira-work	Post a decision confirmation as a comment, set an issue's epic link, create an issue when you ask
Comments on Confluence pages (confluence_comments)	write:comment:confluence	Post an /align reply comment on the originating Confluence page

With a read-only grant, a route that would write to Jira answers 403 write_scope_missing, names the feature and the scope it needs, and writes nothing. If you connect Jira and never use Confluence, the Confluence read scopes stay granted and unused.

Existing connections keep what they granted. Only a new connect starts read-only. An Atlassian grant is per user per app and the newest consent replaces the previous one, so switching a write feature on runs the consent again, asking for the read set, the feature you named, and any write feature the grant already holds. A re-consent never narrows a grant.

Two limits to know. A grant is per user per app, so if the same person connects Jira for a second Align tenant that has no write feature on, Atlassian replaces the first tenant's grant with the read-only one; Align then refuses writes in the first tenant and names the missing scope. And "read-only first" covers connects started from Align: an install started from Slack's or Atlassian's own app page gets whatever the app declares.

Atlassian takes the scope list from each authorisation request, so a Confluence authorisation on its own asks for Confluence read scopes only, with no Jira scope of any kind. That is the grant a tenant holds if they use Confluence and never connect Jira.

Evidence

When a decision is captured from Jira, evidence includes:

• Link to the Jira issue
• Issue key (e.g., PROJ-123)
• Issue title and status
• Related epic (if applicable)

Troubleshooting

Discover finds too many/few results

• Adjust the date range
• Select specific projects
• Use filter keywords

Missing issues

• Ensure Align has access to the project
• Check issue permissions in Jira

Self-Hosted Setup

On Align cloud, Align's OAuth app is used. Self-hosted, you register your own Atlassian app. See OAuth apps.