Linear Integration

Coming Soon — Linear integration is currently in development. Contact us to be notified when it’s available.

Table of contents

1. Overview
2. Prerequisites
3. Setup Instructions
   1. Step 1: Generate Linear API Key
   2. Step 2: Configure ButterStack
   3. Step 3: Team and Project Mapping
   4. Step 4: Webhook Setup
   5. Step 5: Custom Attributes
4. Issue Templates
   1. Asset Review Template
   2. Build Failure Template
5. Workflow Automation
   1. Linear Automations
   2. ButterStack Rules
6. GraphQL API Usage
   1. Get Issues with ButterStack Assets
   2. Create Issue with Asset Link
7. Keyboard Shortcuts
8. Troubleshooting
9. Best Practices
10. Advanced Features
    1. Cycle Integration
    2. Team Insights
11. Next Steps

Overview

Linear integration brings modern, fast issue tracking to ButterStack. Sync tasks, track progress, and manage your asset pipeline with Linear’s keyboard-first interface.

Prerequisites

• Linear workspace (Team or Enterprise plan for API access)
• Admin access to Linear workspace
• ButterStack project with admin rights

Setup Instructions

Step 1: Generate Linear API Key

1. Go to linear.app/settings/api
2. Click Create new API key
3. Name it “ButterStack Integration”
4. Copy the generated key immediately

Step 2: Configure ButterStack

1. Navigate to Settings → Integrations
2. Click Add Integration → Linear
3. Enter configuration:

API Key: lin_api_xxxxxxxxxxxxx
Workspace: your-workspace
Default Team: ENG
Sync Direction: Two-way

Copy API Key Prefix

Step 3: Team and Project Mapping

Map Linear teams to ButterStack projects:

Step 4: Webhook Setup

Configure Linear webhooks for real-time updates:

1. In Linear, go to Settings → API → Webhooks
2. Click New webhook
3. Configure:
   • Label: ButterStack Sync
   • URL: https://app.butterstack.com/webhooks/linear/YOUR_PROJECT_ID
   • Resource types:
     • ✅ Issues
     • ✅ Comments
     • ✅ Projects
     • ✅ Cycles

Step 5: Custom Attributes

Create Linear custom attributes for ButterStack data:

1. Go to Settings → Attributes
2. Create these attributes:
   • ButterStack Asset (URL type)
   • Build Status (Select: Pending, Building, Complete, Failed)
   • Asset Type (Select: Model, Texture, Audio, Animation)
   • Version (Text)

Issue Templates

Create Linear templates for common ButterStack workflows:

Asset Review Template

## Asset Review Request

**Asset Name:** [Asset Name]
**Type:** [Model/Texture/Audio]
**Version:** [v1.0]
**ButterStack Link:** [Link]

### Checklist
- [ ] Technical requirements met
- [ ] Art direction approved
- [ ] Performance validated
- [ ] Integration tested

### Notes
[Additional context]

/label needs-review
/assign @reviewer

Copy Template

Build Failure Template

## Build Failure Report

**Build ID:** #[BUILD_ID]
**Platform:** [Platform]
**Error Type:** [Compilation/Link/Test]

### Error Details

[Error output]

### Steps to Reproduce
1. [Step 1]
2. [Step 2]

### Impact
- **Severity:** [High/Medium/Low]
- **Blocked Assets:** [List]

/label bug build-failure
/priority high

Workflow Automation

Linear Automations

Configure these automations in Linear:

When: Issue moved to "In Review"
And: Has label "asset"
Then: 
  - Create ButterStack approval request
  - Notify assigned reviewer
  - Start review timer

When: Issue moved to "Ready to Build"
And: Has ButterStack Asset linked
Then:
  - Trigger ButterStack build
  - Update issue with build link
  - Add "building" label

When: ButterStack build completes
Then:
  - Move issue to "Done"
  - Add build artifacts link
  - Update version attribute

ButterStack Rules

Set up reciprocal rules in ButterStack:

Rules:
  - name: "Linear Issue Creation"
    trigger: asset.uploaded
    conditions:
      - asset.type in ['model', 'texture']
      - asset.size > 10MB
    actions:
      - create_linear_issue:
          team: "ART"
          title: "Review: ${asset.name}"
          labels: ["asset-review", "${asset.type}"]
          
  - name: "Status Sync"
    trigger: linear.issue.updated
    conditions:
      - issue.state == "completed"
    actions:
      - update_asset_status: "approved"
      - trigger_build: true

GraphQL API Usage

Linear uses GraphQL. Here are useful queries:

Get Issues with ButterStack Assets

query GetButterStackIssues($teamId: String!) {
  issues(
    filter: {
      team: { id: { eq: $teamId } }
      labels: { name: { eq: "butterstack" } }
    }
  ) {
    nodes {
      id
      identifier
      title
      state {
        name
        type
      }
      assignee {
        name
        email
      }
      customAttributes
    }
  }
}

Copy Query

Create Issue with Asset Link

mutation CreateAssetIssue($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    issue {
      id
      identifier
      url
    }
  }
}

# Variables:
{
  "input": {
    "teamId": "TEAM_ID",
    "title": "Asset Review: Character Model v2",
    "description": "Review required for updated character model",
    "labelIds": ["LABEL_ID"],
    "customAttributes": {
      "butterstackAsset": "https://app.butterstack.com/assets/123"
    }
  }
}

Keyboard Shortcuts

Enable ButterStack shortcuts in Linear:

Troubleshooting

curl https://api.linear.app/graphql \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name } }"}'

Best Practices

Advanced Features

Cycle Integration

Align ButterStack milestones with Linear cycles:

Cycle Sync:
  - Linear cycle start → Create ButterStack milestone
  - Add cycle issues → Link related assets
  - Cycle progress → Update build priorities
  - Cycle complete → Generate asset report

Team Insights

Track asset-related metrics in Linear:

• Assets per cycle
• Review turnaround time
• Build success rate by team
• Asset approval velocity

Next Steps

• Compare with Jira integration for enterprise needs
• Set up Trello for visual workflows
• Configure notifications for team updates