Skip to main content

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.

When viewing a Jira issue, click Create Decision in the Align panel.

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​

Align requires these Jira scopes:

ScopePurpose
read:jira-workRead issues and comments
write:jira-workAdd comments (for acknowledgments)
read:jira-userMap Jira users to Align users

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​

See Self-Host OAuth Apps for registering your own Atlassian app.