Skip to main content

Linear Integration

Connect Linear to capture decisions from issues and projects.

Features​

  • Issue capture — Capture decisions from Linear issues
  • Comment capture — Track decisions in issue comments
  • Discover — Scan historical issues for decisions
  • Evidence linking — Link decisions to Linear issues

Setup (Cloud)​

  1. Go to Settings → Integrations in Align
  2. Click Connect Linear
  3. Authorize Align in your Linear workspace
  4. Select which teams to include

Capturing Decisions​

From Issue Comments​

Add a comment to any Linear issue:

@align We decided to implement caching at the API gateway level
rather than in individual services.

From Issue Descriptions​

Include decisions in issue descriptions with clear markers:

## Decision

Moving forward with Redis for session storage because:
- Built-in TTL support
- Team familiarity
- Cluster mode for HA

Discover Mode​

Discover scans your Linear workspace for:

  • Issues with decision-related content
  • Architecture and design discussions
  • Approval and sign-off comments
  • RFC or proposal issues

Running Discover​

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

Best Practices​

  1. Use labels — Tag decision-related issues with a decision label
  2. Document rationale — Include the "why" in issue descriptions
  3. Link related issues — Connect decisions to implementation tasks
  4. Use projects — Group related decisions in Linear projects

Permissions​

Align requires these Linear scopes:

ScopePurpose
readRead issues and comments
writeAdd comments (for acknowledgments)

Evidence​

When a decision is captured from Linear, evidence includes:

  • Link to the Linear issue
  • Issue identifier (e.g., ENG-123)
  • Issue title and status
  • Project name (if applicable)
  • Team name

Troubleshooting​

Align doesn't respond​

  • Ensure Linear is connected in Settings
  • Verify the team is selected in Align
  • Check webhook configuration

Missing issues​

  • Ensure Align has access to the team
  • Check date range in Discover settings

Self-Hosted Setup​

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