linear

Linear

Linear is a streamlined, keyboard-first issue tracking and project management platform designed for high-velocity software engineering teams.

When to Use

High-Velocity Issue Tracking for Engineering Teams: Fast, keyboard-first issue tracking and project management.
Cycles & Project Roadmapping: Planning 2-week engineering cycles, tracking velocity, and milestones.
GitHub & GitLab PR Synchronization: Automatically moving issues to In Progress on branch creation and Done on PR merge.
Linear GraphQL API Automation: Automating issue creation, triage bots, and metrics collection via GraphQL.

Quick Start

# Query Linear GraphQL API for assigned issues
curl -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { assignedIssues(filter: { state: { type: { eq: \"started\" } } }) { nodes { id identifier title } } } }"}'

Core Concepts

Linear GraphQL API Integration with Python

Querying and creating issues programmatically:

import requests
import os

LINEAR_API_URL = "https://api.linear.app/graphql"
API_KEY = os.environ["LINEAR_API_KEY"]

headers = {
    "Authorization": API_KEY,
    "Content-Type": "application/json"
}

# GraphQL Mutation to create an engineering issue
create_issue_mutation = '''
mutation CreateIssue($teamId: String!, $title: String!, $description: String!) {
  issueCreate(input: {
    teamId: $teamId
    title: $title
    description: $description
    priority: 1 # Urgent
  }) {
    success
    issue {
      id
      identifier
      url
    }
  }
}
'''

variables = {
    "teamId": "TEAM_UUID_HERE",
    "title": "Investigate elevated latency on payment webhook worker",
    "description": "P99 latency spiked above 1200ms following deployment v2026.1.0."
}

res = requests.post(LINEAR_API_URL, json={"query": create_issue_mutation, "variables": variables}, headers=headers)
print("Created Issue:", res.json())

Git Branch & PR Automation Rules

Linking code to Linear issues automatically:

# Branch naming convention: <username>/<issue-identifier>-<description>
git checkout -b alice/eng-402-checkout-rate-limit

# Commit message linking
git commit -m "fix(checkout): enforce rate limiting on token endpoint (Fixes ENG-402)"

Linear automatically moves ENG-402 to:

In Progress when the branch is pushed.
In Review when a Pull Request is opened.
Done when the Pull Request is merged into main.

Essential Keyboard Shortcuts

Operating Linear with speed:

C: Create new issue.
Cmd + K: Open Command Menu.
S: Change issue state (Todo, In Progress, Done).
P: Change priority (Urgent, High, Medium, Low).
A: Assign issue to team member.

Common Patterns

Automated Issue Creation via GraphQL API

Problem: Creating Linear tickets automatically from CI/CD alert hooks.
Solution: Execute Linear GraphQL mutation via curl or script.

curl -X POST "https://api.linear.app/graphql" \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation IssueCreate($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id title url } } }",
    "variables": {
      "input": {
        "teamId": "TEAM_UUID",
        "title": "Bug: Production CPU Spike",
        "description": "CPU exceeded 90% on api-gateway-pod-3."
      }
    }
  }'

Best Practices

Do:

Name Git branches using the Linear issue identifier (eng-102-fix-auth) to enable automated status synchronization.
Use Linear's Triage inbox to review and accept incoming bugs and feature requests before backlog addition.
Set issue estimates (points or t-shirt sizes) to track team velocity across cycles.
Use the Linear GraphQL API for automated triage bots and Slack integrations.

Don't:

Leave completed issues un-merged or open; link pull requests so status updates automatically.
Create massive multi-month tickets; break large epics into distinct sub-issues.
Commit LINEAR_API_KEY to public repositories.

Troubleshooting

Error	Cause	Solution
`GraphQL error: 401 Unauthorized`	Invalid `LINEAR_API_KEY` or missing scopes.	Generate API key in Linear Settings > API > Personal API Keys.
`GitHub integration not updating issues`	Webhook disconnected or repository not linked in Linear integration settings.	Re-authenticate GitHub integration in Linear Settings > Integrations.
`Cycle burndown chart not updating`	Issues added to cycle without estimate story points.	Assign points/estimates to issues in cycle backlog.

References

Linear Documentation