Linear Integration - Proliferate

Overview

The Linear integration connects Proliferate with your Linear workspace, enabling seamless error-to-issue workflows. Create Linear issues directly from error detail pages, assign them to team members, and track resolution progress. Key features:

Create Linear issues from errors with one click
Pre-populate issue details from error context
Link errors to existing Linear issues
Select team and assignee for new issues
Track issue status back in Proliferate
Maintain bidirectional links between errors and issues

The Linear integration uses OAuth 2.0 with GraphQL API access. Your access token is encrypted and stored securely.

What You Get

One-Click Issue Creation

Create Linear issues directly from error detail pages

Team & Assignee Selection

Choose which team and member should handle the issue

Pre-Filled Context

Error details, stack traces, and links automatically included

Bidirectional Links

Navigate between errors in Proliferate and issues in Linear

Setup Process

Navigate to Integrations

Go to Settings → Integrations in your Proliferate dashboard.

Connect Linear Workspace

Click Install on the Linear integration card. You’ll be redirected to Linear for authorization.

Authorize Access

On the Linear OAuth page:

Log in to your Linear account if prompted
Review the requested permissions
Select the workspace to connect
Click Authorize to grant access

You can connect one Linear workspace per Proliferate organization. To change workspaces, disconnect and reconnect.

Select Default Team

After authorization:

Choose a default team for new issues
This can be changed when creating individual issues
The default team is used for quick issue creation

Test the Connection

Verify everything is working:

Go to any error detail page
Click Create Linear Issue
You should see your teams and members in the dropdown

Creating Issues from Errors

From the Error Detail Page

The most common workflow for creating Linear issues:

Navigate to an Error:
- Go to your Issues page
- Click on any error to view details
Click “Create Linear Issue”:
- Find the Linear button in the error detail header
- A modal will open with issue creation options

Configure the Issue:

Team: [Select team]
Assignee: [Select team member] (optional)
Title: [Pre-filled from error]
Description: [Pre-filled with error details]

Review Pre-Filled Details: The issue description automatically includes:
- Error type and message
- Stack trace
- First seen and last seen timestamps
- Affected user count
- Environment and release information
- Direct link back to the error in Proliferate
Create the Issue:
- Click Create Issue
- The issue is created in Linear
- A link appears in the error detail page
- You’re redirected to the new Linear issue

Issue Template

Created issues follow this template:

# Error: TypeError: Cannot read property 'user' of undefined

**Error Details:**
- **Type:** TypeError
- **Message:** Cannot read property 'user' of undefined
- **Environment:** production
- **Release:** v1.2.3
- **First Seen:** 2024-01-15 10:30:00 UTC
- **Last Seen:** 2024-01-15 14:45:00 UTC
- **Affected Users:** 12

**Stack Trace:**

at getUserProfile (app.js:42:15) at handleRequest (app.js:120:5) …

**Links:**
- [View in Proliferate](https://app.proliferate.com/issues/123)

---
*This issue was automatically created from Proliferate.*

Linking Existing Issues

Instead of creating a new issue, you can link an error to an existing Linear issue:

Copy Linear Issue URL

From Linear, copy the URL of the issue you want to link (e.g., https://linear.app/yourteam/issue/PRO-123)

Add Link in Proliferate

In the error detail page:

Find the “Linked Issues” section
Click Add Link
Paste the Linear issue URL
Click Save

View the Link

The linked issue appears with:

Linear issue identifier (e.g., PRO-123)
Issue title
Current status
Quick link to open in Linear

Team and Member Selection

Selecting a Team

When creating an issue, choose which Linear team should own it:

Fetch Teams:

GET /api/v1/integrations/linear/teams

Returns all teams in your workspace:

{
  "teams": [
    {
      "id": "team_abc123",
      "name": "Engineering",
      "key": "ENG",
      "description": "Product engineering team"
    }
  ]
}

Select Team:
- Choose from the dropdown
- Each team has a unique prefix (e.g., ENG, PRO, DES)
- This prefix appears in issue identifiers (ENG-123)

Selecting an Assignee

Optionally assign the issue to a team member:

Fetch Team Members:

GET /api/v1/integrations/linear/teams/{team_id}/members

Returns members of the selected team:

{
  "members": [
    {
      "id": "user_xyz789",
      "name": "Jane Doe",
      "email": "[email protected]",
      "avatar_url": "https://..."
    }
  ]
}

Assign Member:
- Select from the dropdown (optional)
- Leave blank for unassigned
- The assignee is notified in Linear

Testing Your Connection

After connecting Linear, verify the integration:

Test API Access:
```
GET /api/v1/integrations/linear/test
```
Response includes:
- Connected Linear user and email
- Workspace/organization name
- Sample recent issues from the workspace
Create a Test Issue:
- Navigate to any error
- Click Create Linear Issue
- Fill in the details
- Verify the issue appears in Linear

API Endpoints

The Linear integration provides these endpoints:

Endpoint	Method	Description
`/api/v1/integrations/linear/connect`	GET	Start Linear OAuth flow
`/api/v1/integrations/linear/callback`	GET	Handle OAuth callback
`/api/v1/integrations/linear/test`	GET	Test connection and view workspace info
`/api/v1/integrations/linear/teams`	GET	List all teams in workspace
`/api/v1/integrations/linear/teams/{id}/members`	GET	List members of a specific team
`/api/v1/integrations/linear/issues`	POST	Create a new Linear issue
`/api/v1/integrations/linear/disconnect`	DELETE	Remove Linear connection

Creating Issues Programmatically

You can create Linear issues via the API:

curl -X POST "https://api.proliferate.com/api/v1/integrations/linear/issues" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "team_abc123",
    "title": "Fix critical error in user profile",
    "description": "TypeError when loading user profile...",
    "assignee_id": "user_xyz789"
  }'

Response:

{
  "success": true,
  "issue_id": "issue_123",
  "issue_identifier": "ENG-42",
  "issue_url": "https://linear.app/yourteam/issue/ENG-42",
  "title": "Fix critical error in user profile"
}

Troubleshooting

Can't see teams or members

Checklist:

Verify the Linear integration is connected
Check that you have access to teams in Linear
Ensure your Linear account has permission to create issues
Try disconnecting and reconnecting the integration

OAuth token expired

Linear OAuth tokens are long-lived but can expire:

You’ll see authentication errors when creating issues
Disconnect and reconnect the integration
Re-authorize with Linear
Token will be refreshed automatically

Issue creation fails

Common errors:

401 Unauthorized: Token expired, reconnect integration
403 Forbidden: Insufficient permissions in Linear
400 Bad Request: Invalid team_id or assignee_id
Check the error message for specific details

Missing issue details

If created issues are missing information:

Verify error context is complete (environment, release, etc.)
Check that stack traces are being captured
Ensure source maps are uploaded for better stack traces

Permissions Required

The Linear integration requests these OAuth scopes:

Scope	Purpose
`read`	Read workspace, teams, issues, and members
`write`	Create and update issues
`issues:create`	Specifically create new issues

The integration can only create issues and read workspace data. It cannot delete issues or modify other workspace settings.

Understanding Created Issues

Each issue created from Proliferate includes:

Field	Source
Title	Error type and message
Description	Full error details (see template above)
Team	Selected team
Assignee	Selected team member (optional)
Labels	None by default (can be added in Linear)
Priority	None by default (can be set in Linear)
Project	None by default (can be set in Linear)

You can modify any of these fields in Linear after creation.

Best Practices

Set Default Teams

Configure default teams for common error types. This speeds up issue creation and ensures proper routing.

Use Meaningful Titles

While titles are pre-filled, edit them to be more descriptive and actionable. Good titles help with issue prioritization.

Add Context in Linear

After creating an issue, add additional context in Linear:

Set priority based on user impact
Add labels for categorization
Link to related issues
Add to relevant projects or cycles

Track Resolution

When an issue is fixed:

Mark the Linear issue as completed
Verify the error stops occurring in Proliferate
Update the error status in Proliferate

Don't Duplicate Issues

Before creating a new issue, check if one already exists for the same error. Use the linking feature for existing issues.

Managing the Integration

Changing Default Team

To update the default team for new issues:

Go to Settings → Integrations
Click on the Linear integration
Select a new default team from the dropdown
Click Save

Viewing Created Issues

To see all issues created from Proliferate:

In Linear, use the filter: created by:Proliferate
Or search for issues with the description text “automatically created from Proliferate”

Disconnecting Linear

To remove the integration:

Disconnect in Proliferate

Go to Settings → Integrations
Click disconnect on the Linear card
Confirm the disconnection

Revoke OAuth (Optional)

Go to Linear workspace settings
Navigate to Security → Authorized Applications
Revoke access for Proliferate

Disconnecting the integration will prevent creating new Linear issues. Existing links between errors and issues will remain, but the links may become stale if the Linear token is revoked.

Workflow Examples

Example 1: Critical Production Error

Error Occurs: User reports critical error in production
Investigate: View error details in Proliferate
Create Issue: Click “Create Linear Issue”
- Select team: Engineering
- Assign to: On-call engineer
- Priority: Urgent
Fix: Engineer resolves the issue
Verify: Check Proliferate to confirm error stopped
Close: Mark Linear issue as completed

Example 2: Recurring Error Pattern

Identify Pattern: Notice an error occurring repeatedly
Create Issue: Create Linear issue for investigation
- Select team: Engineering
- Add label: “needs-investigation”
Investigate: Team member investigates root cause
Plan Fix: Add fix to sprint/cycle in Linear
Implement: Engineer implements fix
Monitor: Watch error in Proliferate to confirm fix works
Complete: Close Linear issue when resolved

GraphQL Queries

The integration uses Linear’s GraphQL API. Example queries:

Fetch Teams

query {
  teams {
    nodes {
      id
      name
      key
      description
    }
  }
}

Create Issue

mutation CreateIssue($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    success
    issue {
      id
      identifier
      url
      title
    }
  }
}

Fetch Team Members

query GetTeamMembers($teamId: String!) {
  team(id: $teamId) {
    members {
      nodes {
        id
        name
        email
        avatarUrl
      }
    }
  }
}

Integrations

​Overview

​What You Get

One-Click Issue Creation

Team & Assignee Selection

Pre-Filled Context

Bidirectional Links

​Setup Process

​Creating Issues from Errors

​From the Error Detail Page

​Issue Template

​Linking Existing Issues

​Team and Member Selection

​Selecting a Team

​Selecting an Assignee

​Testing Your Connection

​API Endpoints

​Creating Issues Programmatically

​Troubleshooting

​Permissions Required

​Understanding Created Issues

​Best Practices

​Managing the Integration

​Changing Default Team

​Viewing Created Issues

​Disconnecting Linear

​Workflow Examples

​Example 1: Critical Production Error

​Example 2: Recurring Error Pattern

​GraphQL Queries

​Fetch Teams

​Create Issue

​Fetch Team Members

Overview

What You Get

Setup Process

Creating Issues from Errors

From the Error Detail Page

Issue Template

Linking Existing Issues

Team and Member Selection

Selecting a Team

Selecting an Assignee

Testing Your Connection

API Endpoints

Creating Issues Programmatically

Troubleshooting

Permissions Required

Understanding Created Issues

Best Practices

Managing the Integration

Changing Default Team

Viewing Created Issues

Disconnecting Linear

Workflow Examples

Example 1: Critical Production Error

Example 2: Recurring Error Pattern

GraphQL Queries

Fetch Teams

Create Issue

Fetch Team Members