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.

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​

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​

Self-hosted Align uses Align's centrally-managed Atlassian app by default - see Connector Authentication, which also covers what to do if your security policy requires your own app.