Skip to main content

Linear Integration Setup

Complete guide to connecting Distil with your Linear workspace.

What You'll Need​

Before starting:

  • Linear account (any plan works)
  • Admin role in your Distil workspace
  • Workspace access in Linear (can create issues)
  • 10 minutes

How Linear Integration Works​

When you push a card to Linear:

  1. Distil creates a new Linear issue
  2. The issue includes the card title, description, and tags
  3. A backlink to Distil is added to the issue
  4. The Distil card status changes to "Ready"
  5. The Linear issue link is saved on the card

Step 1: Connect Linear​

  1. Log in to Distil
  2. Go to Settings → Integrations
  3. Find the Linear card
  4. Click "Connect Linear"
  5. Sign in with your Linear account (if not already signed in)
  6. Click "Authorize" to grant Distil access

You'll be redirected back to Distil with a success message.

Step 2: Configure Default Team​

After connecting, choose which Linear team cards should push to.

  1. In the Linear integration settings, click "Configure Team"
  2. Select a team from the dropdown (e.g., "Product")
  3. Click "Save"

Tip: Choose the team where you manage product backlog, not support or ops teams.

Step 3: Test the Integration​

Create a test card and push it to Linear:

  1. Go to your Distil dashboard
  2. Create a new card: "Test Linear Integration"
  3. Accept the card with rationale: "Testing Linear integration"
  4. Click "Push to Linear" at the bottom of the card
  5. Confirm the push

Then check Linear:

  • Open your configured Linear team
  • Find the new issue (should appear within seconds)
  • Verify the description includes a link back to Distil
  • Check that Distil tags were converted to Linear labels

If this works, you're all set!

Step 4: Configure Team Workflow​

Decide how your team will use the integration:

Option 1: PM-Only Pushing​

PMs push to Linear, engineers work in Linear exclusively.

Workflow:

  1. PM reviews feedback in Distil
  2. PM accepts and pushes to Linear when ready
  3. Engineers pick up issues from Linear backlog
  4. Engineers never need Distil access

Pros: Simple, clear ownership Cons: PM is a bottleneck for pushing

Option 2: Collaborative Pushing​

PMs and tech leads both can push from Distil.

Workflow:

  1. PM accepts cards in Distil
  2. Either PM or tech lead pushes to Linear during planning
  3. Engineers work in Linear

Pros: Flexible, no bottleneck Cons: Requires coordination

Option 3: Sprint Planning Push​

PM batches accepted cards and bulk-pushes before each sprint.

Workflow:

  1. PM accumulates accepted cards throughout sprint
  2. Before sprint planning, PM bulk-pushes ready items
  3. Team reviews Linear backlog in planning meeting
  4. Engineers pull from Linear during sprint

Pros: Efficient, batched workflow Cons: Cards don't flow to Linear until planning

What Gets Pushed to Linear​

When you push a card, Distil creates a Linear issue with:

Title: Card title (exact copy)

Description: Formatted markdown including:

  • Original feedback/problem description
  • Link back to Distil card
  • Acceptance rationale (if Governance Pack enabled)
  • Accepted by and date (if Governance Pack enabled)

Labels: Distil tags are converted to Linear labels

Team: Your configured default team

Project: Not automatically assigned (you can assign in Linear)

Status: "Backlog" (Linear's default for new issues)

Team Overrides (Advanced)​

By default, all cards push to your configured team. But you can override per-push:

When you'd want this:

  • You have multiple Linear teams (Product, Engineering, Design)
  • You want to route cards to different teams based on type

How to override:

  1. When pushing, click "Advanced Options"
  2. Select a different team
  3. Push

The override applies only to that push - your default remains unchanged.

Every Linear issue created from Distil includes a link back to the Distil card.

Format: "View in Distil: [link]" at the bottom of the description

Why this matters: Engineers can jump back to Distil to see:

  • Original customer feedback
  • Signal notes showing patterns
  • Acceptance rationale
  • Full context for why this work matters

After Pushing​

Once pushed:

  • Card status changes to "Ready" in Distil
  • Linear link is saved on the Distil card
  • Card stays in Distil as a record

You manage the work in Linear from this point. The Distil card is now a historical record.

Governance Pack Features​

If you have the Governance Pack enabled, pushed Linear issues include:

Acceptance rationale: Why this was prioritized Accepted by: Which PM accepted this Accepted date: When it was accepted

This creates full traceability from feedback → decision → engineering work.

Learn more about Governance Pack

Linear vs. Jira​

Both integrations work similarly, but there are differences:

FeatureLinearJira
Setup complexitySimpleModerate
OAuth flowFastSlower
ConfigurationOne teamProject + issue type
PerformanceVery fastModerate
Issue formatMarkdownADF (custom format)
LabelsAuto-createdAuto-created

Bottom line: Linear is simpler and faster. Jira has more configuration options.

You can use both integrations simultaneously if you work with both tools.

Security and Privacy​

OAuth Token Storage​

Distil stores your Linear OAuth token securely in encrypted database fields. Tokens are never logged or exposed.

Token Refresh​

Linear tokens don't expire automatically. You only need to reconnect if you revoke access.

Data Access​

Distil can only:

  • Read team metadata (to show you options)
  • Create issues in teams you select
  • View issues created by Distil (to show you links)

Distil cannot:

  • Read other Linear issues
  • Modify issues not created by Distil
  • Access Linear user data
  • Delete issues

Revoking Access​

To disconnect Linear:

  1. Go to Settings → Integrations
  2. Click "Disconnect Linear"
  3. Confirm

Your token is deleted immediately. Existing Linear issues remain unchanged.

Best Practices​

Use Linear's Native Labels​

Don't over-tag in Distil. Linear labels are valuable - only push tags that matter for filtering in Linear.

Push in Batches​

During sprint planning, bulk-push all cards ready for the sprint. More efficient than pushing one-by-one.

Keep Acceptance Rationale Clear​

Engineers see this context in Linear. Explain why this matters, not just what it is.

Don't Delete Linear Issues After Pushing​

If you delete a Linear issue, the Distil card still thinks it's pushed. Instead, cancel or archive the issue in Linear.

Use Linear Projects​

After pushing, assign issues to Linear projects or milestones for better organization.

Troubleshooting​

See Troubleshooting Linear Integration for common issues.

Quick fixes:​

"Not connected": Go to Settings → Integrations and reconnect Linear

"No team configured": Go to Settings → Integrations and select a default team

"Card must be accepted first": Only accepted cards can be pushed

"Already pushed": This card was already pushed. Check the Linear link on the card.

"Permission denied": Your Linear account needs permission to create issues in the team

Next Steps​