Linear

Linear is a community skill for integrating with the Linear project management platform through its API, enabling automated issue creation, status tracking, cycle management, workflow synchronization with development tools, and automated sprint reporting.

What Is This?

Overview

Linear provides integration patterns for the Linear project management API, covering issue lifecycle operations, label and status management, cycle and project tracking, webhook event handling, and team workflow automation. The skill enables development teams to synchronize their code workflows with Linear project tracking, keeping issues updated automatically as pull requests progress through review and deployment stages.

Who Should Use This

This skill serves engineering teams using Linear for project management, DevOps engineers connecting CI/CD pipelines to issue tracking, and developers building custom integrations that automate repetitive project management tasks such as issue triage, status updates, and sprint planning.

Why Use It?

Problems It Solves

Manual issue status updates fall behind actual development progress, creating stale project boards. Developers switch context between code editors and project management tools to log work status. Sprint planning requires manual aggregation of issue estimates and team capacity data. Without webhook integration, downstream systems have no real-time visibility into project state changes.

Core Highlights

GraphQL API provides fine-grained queries for issues, projects, cycles, and team data. Webhook events notify external systems of state changes in real time. Batch operations update multiple issues simultaneously for sprint transitions and bulk triage. Label and status automation applies consistent categorization rules across incoming issues.

How to Use It?

Basic Usage

import httpx
from dataclasses import dataclass

@dataclass
class LinearClient:
    api_key: str
    base_url: str = "https://api.linear.app/graphql"

    def query(self, gql: str, variables: dict = None) -> dict:
        resp = httpx.post(
            self.base_url,
            headers={"Authorization": self.api_key},
            json={"query": gql, "variables": variables or {}}
        )
        resp.raise_for_status()
        return resp.json()["data"]

    def create_issue(self, team_id: str, title: str,
                     description: str = "") -> dict:
        mutation = """
        mutation($input: IssueCreateInput!) {
            issueCreate(input: $input) {
                issue { id identifier title url }
            }
        }"""
        return self.query(mutation, {"input": {
            "teamId": team_id, "title": title,
            "description": description
        }})

Real-World Examples

class SprintManager:
    def __init__(self, client: LinearClient, team_id: str):
        self.client = client
        self.team_id = team_id

    def get_active_cycle(self) -> dict:
        query = """
        query($teamId: String!) {
            team(id: $teamId) {
                activeCycle {
                    id name startsAt endsAt
                    issues { nodes { id title state { name } } }
                }
            }
        }"""
        data = self.client.query(query, {"teamId": self.team_id})
        return data["team"]["activeCycle"]

    def cycle_stats(self) -> dict:
        cycle = self.get_active_cycle()
        if not cycle:
            return {"status": "no active cycle"}
        issues = cycle["issues"]["nodes"]
        by_state = {}
        for issue in issues:
            state = issue["state"]["name"]
            by_state[state] = by_state.get(state, 0) + 1
        return {
            "cycle": cycle["name"],
            "total_issues": len(issues),
            "by_state": by_state
        }

Advanced Tips

Use Linear webhooks to trigger CI pipelines when issues move to specific states. Implement pagination for large issue queries using cursor-based pagination patterns. Create custom workflow automations that transition issues based on Git branch and pull request events from your repository hosting platform.

When to Use It?

Use Cases

Automatically create Linear issues from bug reports submitted through customer support channels. Sync issue status with pull request state so boards update when code is merged. Generate sprint velocity reports by querying completed cycle data through the API.

Related Topics

GraphQL API design, project management automation, webhook event processing, issue tracking integration patterns, and developer workflow optimization.

Important Notes

Requirements

A Linear workspace with API access enabled, an API key or OAuth token with appropriate scopes, and an HTTP client supporting GraphQL requests.

Usage Recommendations

Do: use GraphQL query fragments to request only the fields you need, reducing response payload size. Implement webhook signature verification for secure event handling. Batch related issue updates into single operations when possible.

Don't: poll the API for status changes when webhooks provide real-time notifications. Create overly complex GraphQL queries that fetch deeply nested data in a single request. Store API tokens in client-side code or commit them to version control.

Limitations

GraphQL rate limits restrict the number of API calls per time window. Webhook delivery is not guaranteed and requires retry handling for missed events. Complex custom field configurations may not be fully accessible through the public API. Integration testing requires a dedicated workspace to avoid affecting production data.