> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear

> Integration details and setup guide for the Linear connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                                                   |
| ----------------------------------- | ------------------------------------------------------------------------- |
| **Authentication**                  | OAuth 2.0 (Authorization Code with refresh tokens) or Bearer Token        |
| **Two-Way Sync**                    | No                                                                        |
| **Events Supported**                | No                                                                        |
| **Realtime**                        | Polling                                                                   |
| **Supports Rate Limiting**          | Yes                                                                       |
| **Authentication Scopes Supported** | `read`, `write`, `issues:create`, `comments:create`, `timeSchedule:write` |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **Linear**:

* **Users**
* **Comments**
* **Projects**
* **Workflow States**
* **Labels**
* **Teams**

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                             |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Offers free trial?**                             | Yes. Linear offers a free plan for individuals and small teams. Sign up at [https://linear.app/signup](https://linear.app/signup). |
| **Requires paid sandbox**                          | No. The free plan can be used for development and testing.                                                                         |
| **Requires partnership to obtain authentication?** | No. Anyone can create a Linear account and OAuth application.                                                                      |

***

### Authentication (OAuth 2.0)

For customers who want to completely whitelabel their OAuth experience, you can provide your own developer keys instead of using Alloy Automation's.

#### Create your OAuth app

1. **Create a Linear account** at [https://linear.app](https://linear.app)
2. **Navigate to Settings** > **API** > **Applications**
3. Click **Create new application** ([https://linear.app/settings/api/applications/new](https://linear.app/settings/api/applications/new))
4. Fill in your application details:
   * **Name**: Your application name
   * **Description**: Brief description of your app
   * **Website URL**: Your application's website
5. **Configure OAuth settings**:
   * Add the redirect URI: `https://api.runalloy.com/api/strategy/connector/linear/callback`
   * Select required scopes:
     * `read` - Read access for the user's account
     * `write` - Write access for the user's account
     * `issues:create` - Create new issues and attachments
     * `comments:create` - Create new issue comments
     * `timeSchedule:write` - Create and modify time schedules
   * Note: Scopes are comma-separated
6. Copy your **Client ID** and **Client Secret**
7. Configure these credentials in Alloy Automation

#### API Documentation

* Linear API: [https://developers.linear.app/docs](https://developers.linear.app/docs)
* GraphQL API Endpoint: [https://api.linear.app/graphql](https://api.linear.app/graphql)
* OAuth Guide: [https://developers.linear.app/docs/oauth/authentication](https://developers.linear.app/docs/oauth/authentication)

***

## Use Cases

### 1) Automated issue creation from support tickets

Automatically create Linear issues when customer support tickets are submitted, bug reports are filed, or monitoring alerts are triggered, ensuring engineering teams have visibility into all product issues.

### 2) Project management synchronization

Sync Linear projects, teams, and workflow states to other project management tools, enabling cross-functional teams to work in their preferred platforms while maintaining a single source of truth.

### 3) Engineering metrics and analytics

Pull Linear issue data, state transitions, and completion times into analytics platforms to calculate velocity, cycle time, lead time, and other engineering performance metrics.

### 4) Cross-platform collaboration

Integrate Linear with Slack, Microsoft Teams, or other collaboration tools to post issue updates, comments, and status changes, keeping distributed teams informed in real-time.

### 5) Automated workflow orchestration

Trigger automated workflows based on Linear issue state changes, such as notifying stakeholders when issues move to specific states, updating external systems, or creating follow-up tasks.

***

## API Gotchas

* **GraphQL API**: Linear uses GraphQL instead of REST. All API calls are POST requests to `https://api.linear.app/graphql` with a GraphQL query in the request body. This is different from traditional REST APIs and requires understanding GraphQL query syntax.
* **Cursor-based pagination**: Linear uses cursor-based pagination for list queries. Store the `endCursor` from `pageInfo` to fetch the next page. The pagination uses `first`/`after` or `last`/`before` parameters for forward and backward pagination.
* **Field selection**: GraphQL requires you to explicitly specify which fields you want in the response. Missing required fields in your query will result in incomplete data. Use the `returnFields` configuration to specify all needed fields.
* **Scope delimiter**: Linear uses commas (`,`) to separate OAuth scopes, not spaces. When requesting multiple scopes, format them as `read,write,issues:create`.
* **Rate limiting**: Linear enforces rate limits per user and per application. Implement exponential backoff when receiving rate limit errors. The API typically returns rate limit information in error responses.
* **Team and organization context**: Many Linear resources are scoped to specific teams or organizations. Ensure your queries include appropriate team or organization filters to retrieve the correct data.
* **Date formats**: Linear uses ISO 8601 date-time format for all timestamp fields. Ensure your integration correctly parses these timestamps when processing issue creation dates, updates, and deadlines.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.