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

# Linear

> Connect Linear so agents can search issues, projects, and cycles, flag blocked work, and update issues through your Approvals

Connect Linear so [CloudThinker](https://docs.cloudthinker.io/guide/agents/overview.md) can search issues, projects, cycles, and comments, flag work that's blocked or overdue, and create or update issues when you ask. Linear uses OAuth through its hosted MCP server, so there's no API key to create or paste.

## Prerequisites

* A Linear account that belongs to the teams you want CloudThinker to read.
* Permission in your Linear workspace to authorize a third-party app.
* The **Admin** role in your CloudThinker workspace, which can add and edit connections. See [Roles](https://docs.cloudthinker.io/guide/security/roles.md). Linear works on every CloudThinker plan.

## Setup

**1. Open Linear in CloudThinker**

In the sidebar, click **More → Workspace settings → Connections**. On the **Builtin Connections** tab, search for **Linear** and click **Connect**.

**2. Authorize in Linear**

Linear opens in a new window. If your browser blocks it, a dialog appears instead: click **Open Linear**. Sign in with the account whose teams CloudThinker should see, pick the right Linear workspace if you belong to more than one, and approve access. The window closes on its own.

**3. Return to CloudThinker**

CloudThinker stores the OAuth tokens and tests the connection.

**Success state:** Linear shows a **Connected** status.

## Connection details

There are no fields to fill in.

| Item | Description |
| - | - |
| **OAuth tokens** | Issued by Linear when you approve access and stored by CloudThinker. Reconnect to replace them. |

A CloudThinker workspace holds one Linear connection, so it reaches the one Linear workspace you picked. To use a different Linear workspace, disconnect and connect again, then pick it during authorization.

## Required permissions

CloudThinker acts as the Linear account that authorized the connection. It sees the teams, projects, and issues that account can see, and nothing else.

| Access | What it covers |
| - | - |
| **Read** | Teams, users, projects, milestones, cycles, issue statuses, labels, issues, comments, documents, and attachments |
| **Write** | Create or update issues, comments, projects, milestones, and documents; add labels and attachments; delete comments and attachments |

Reads run without asking.

Every change an agent makes goes through your workspace's [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) first. On the default **Auto · Rules + AI · Ask me** mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on [Rule enforcement](https://docs.cloudthinker.io/guide/approvals/rules.md#troubleshooting) for your workspace. Choose **Manual** to approve every change yourself.

In chat, CloudThinker only proposes a write when you name the item and the change. Resolve follow-up issues are the exception: they run under the outcome you turn on in [Resolve Triggers & Outcomes](https://docs.cloudthinker.io/guide/incident/triggers-and-outcomes.md#outcomes).

> [!TIP]
>
> Authorize with an account that belongs only to the teams CloudThinker needs. Actions in Linear appear as that account, so a dedicated account makes agent changes easy to spot. On a paid Linear plan, a dedicated account takes a seat.

## Agent capabilities

| Capability | What CloudThinker does | Approval |
| - | - | - |
| **Workspace discovery** | Lists teams with their keys (such as `ENG`), projects, users, and labels | No |
| **Issue search** | Finds issues by team, cycle, assignee, status, or text, and reads their comments | No |
| **Cycle and project review** | Shows what a cycle or project holds and which issues are off track | No |
| **Blocked work** | Surfaces issues that are blocked, overdue, unassigned, or sitting in one status too long | No |
| **Ticket context in Review** | Pulls the Linear issue a merge or pull request references (for example `ENG-123`) into [Review](https://docs.cloudthinker.io/guide/code-review/overview.md) | No |
| **Issue changes** | Creates or updates an issue, sets priority or assignee, or adds a comment | Through Approvals |
| **Project and document changes** | Creates or updates a project, milestone, or document; adds labels or attachments | Through Approvals |
| **Deletes** | Deletes a comment or an attachment | Through Approvals |
| **Follow-up tickets in Resolve** | Files and updates follow-up issues after an incident, once you turn on the outcome in [Resolve Triggers & Outcomes](https://docs.cloudthinker.io/guide/incident/triggers-and-outcomes.md#outcomes) | Set by the outcome |

### Verify the connection

```text theme={null}
List my Linear teams with their keys, then summarize the current cycle for one of them
```

You should get team names with keys you recognize and a list of issue identifiers like `ENG-123` from the current cycle.

### Example prompts

```text theme={null}
Which issues in the ENG team's current cycle are blocked or past their due date?
Rank the unassigned issues in the Platform team by priority and age
Create an Urgent issue in ENG titled "Checkout API returns 502 under load" and assign it to Dana Lee
```

The third prompt is a write, so it goes through Approvals. When it asks you, CloudThinker shows the issue it will create first. Name the assignee: "me" means the account that authorized the connection, not you.

## Troubleshooting

> [accordion] The OAuth page doesn't finish
>
> Your browser is signed in to the wrong Linear account, or not signed in at all. Sign in to the intended account and click **Connect** again from **More → Workspace settings → Connections**.

> [accordion] Expected teams or issues are missing
>
> The account that authorized the connection isn't a member of those teams, or you picked a different Linear workspace during OAuth. Add the account to the team in Linear, or reconnect and pick the right workspace.

> [accordion] An agent says an issue was not found
>
> The identifier is wrong or belongs to a team the account can't see. Check the exact identifier in Linear (for example `ENG-123`) and confirm the account's team access. This is not a broken connection.

> [accordion] The connection worked, then requests fail with 401
>
> The authorization expired or was revoked in Linear. Reconnect Linear from **More → Workspace settings → Connections**.

> [accordion] Requests fail with 429
>
> Linear limits how many requests one user can make in a short window. Wait about a minute, then retry with a narrower request, such as one team or one cycle.

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Changes appear as the authorizing user.** Use a dedicated Linear account so your team can tell agent changes apart in issue history.
- **Deletes stay narrow.** The only deletes are comments and attachments, and each one goes through Approvals.
- **Revoke in Linear too.** When you remove the connection, also revoke CloudThinker's access in your Linear account settings.

## Related

> [card] [Connections](https://docs.cloudthinker.io/guide/connections/overview.md)
>
> Browse every service CloudThinker agents can use.

> [card] [Resolve Triggers & Outcomes](https://docs.cloudthinker.io/guide/incident/triggers-and-outcomes.md#outcomes)
>
> Turn on follow-up tickets in Linear after an incident.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.