> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/use-groundcover/connectors/linear.md).

# Linear

The Linear connector links a Linear workspace to groundcover. After it is configured, you can:

* Create a Linear issue directly from a monitor issue
* Create and update Linear issues automatically through [Notification Routes](/use-groundcover/monitors/notification-routes.md)
* Connect your personal Linear account so [Agent Mode](/use-groundcover/agent-mode.md) can use Linear MCP tools on your behalf

{% hint style="info" %}
A groundcover workspace admin must set up the organization connector. Afterward, individual users can connect their own Linear accounts for Agent Mode.
{% endhint %}

## How the Linear connections work

Linear uses two related connections:

| Connection                 | Who configures it             | What it enables                                                                                      |
| -------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Organization connector** | A groundcover workspace admin | Manual issue creation from monitor issues and automated issue management through Notification Routes |
| **Personal connection**    | Each groundcover user         | Linear MCP tools in Agent Mode, using that user's Linear permissions                                 |

The organization connector is required before users can create personal connections.

## Prerequisites

Before you begin, make sure you have:

* Admin permissions in groundcover
* Permission to create an OAuth application in the Linear workspace you want to connect
* Access to that Linear workspace during the OAuth approval flow

## Set up the organization connector

Setting up the organization connector is a one-time process for each Linear workspace.

### Step 1: Open the Linear connector setup

1. In groundcover, go to **Integrations → Connectors**.
2. Open the **Org Connectors** tab.
3. In the Linear section, enter a unique **Connector Name**. This name identifies the Linear workspace throughout groundcover.
4. Click **Create App**.

<div data-with-frame="true"><figure><img src="/files/DM6DUDbpsEmfvKU7V4i6" alt="Linear organization connector setup in groundcover"><figcaption><p>Create a Linear OAuth app and enter its Client ID in the organization connector setup.</p></figcaption></figure></div>

{% hint style="info" %}
Click **View Manifest** if you want to inspect the application manifest before continuing.
{% endhint %}

### Step 2: Create the OAuth application in Linear

Linear opens in a new tab with the application fields populated from the groundcover manifest. Review the target workspace, then click **Create**. No changes to the pre-filled settings are required.

<div data-with-frame="true"><figure><img src="/files/dZE3zbbP3zeg9pXea6Uj" alt="Pre-filled groundcover OAuth application in Linear"><figcaption><p>Linear populates the application name, description, and redirect URI from the manifest.</p></figcaption></figure></div>

The application remains private to your Linear workspace.

### Step 3: Copy the Linear Client ID

After Linear creates the application, open its settings and scroll to **OAuth credentials**. Copy the **Client ID**.

<div data-with-frame="true"><figure><img src="/files/iE3XYfBVxcYtEdvRMpRx" alt="Client ID in the Linear OAuth credentials section"><figcaption><p>Copy the Client ID from the application's OAuth credentials.</p></figcaption></figure></div>

{% hint style="warning" %}
Only copy the **Client ID** into groundcover. Do not copy or share the Client secret.
{% endhint %}

### Step 4: Connect and authorize the application

1. Return to the groundcover connector setup tab.
2. Paste the value into **Linear OAuth Client ID**.
3. Click **Connect**.
4. On the Linear OAuth approval page, select the correct workspace and approve the application.

After authorization returns you to groundcover, the Linear workspace appears under **Org Connectors** and is ready to use.

<div data-with-frame="true"><figure><img src="/files/gg6vWUKHXwjrJTqZfExG" alt="Connected Linear workspace in groundcover organization connectors"><figcaption><p>The connected Linear workspace is available to the organization.</p></figcaption></figure></div>

To connect another Linear workspace, click **Add Another** and repeat the setup with a unique Connector Name.

## Connect your personal Linear account for Agent Mode

After an admin configures the organization connector, each user can enable Linear MCP tools for Agent Mode:

1. Go to **Integrations → Connectors**.
2. Open **My Connections**.
3. Find the Linear workspace you want to use and click **Connect**.
4. Approve the connection in Linear.

<div data-with-frame="true"><figure><img src="/files/EQIDztfGnzpPrEQuAAO0" alt="Linear connector available under My Connections"><figcaption><p>Connect your Linear account to make its MCP tools available to Agent Mode.</p></figcaption></figure></div>

Agent Mode can now use Linear within the permissions of your connected Linear account. For example, you can ask it to create an issue, find issues assigned to you, or update an existing issue.

## Create a Linear issue from a monitor issue

To create and link a Linear issue manually:

1. Go to **Monitors → Monitor Issues** and open an issue.
2. Click the Linear icon in the issue actions. Its tooltip reads **Create Linear issue**.

<div data-with-frame="true"><figure><img src="/files/DiqIrmK3TfUAdWM1ZGHM" alt="Create Linear issue action on a groundcover monitor issue"><figcaption><p>Create a Linear issue directly from the monitor issue details.</p></figcaption></figure></div>

3. Review the pre-filled title and description.
4. Select a Linear team and, optionally, a project, labels, assignee, and status.
5. Create the issue.

The new Linear issue includes monitor context and links back to groundcover. After an issue is linked, groundcover shows actions for opening it or adding an update instead of creating a duplicate.

## Automate Linear issues with a Notification Route

Use a Notification Route to keep a Linear issue synchronized with a monitor issue throughout its lifecycle:

1. Go to **Monitors → Notification Routes**.
2. Create a route or edit an existing one.
3. Define the monitor scope for the route.
4. In **Step 3: Rules**, select **Firing** and **Resolved**.
5. Under **Send to**, select your Linear connector.
6. Select the required Linear **Team**.
7. **Auto-resolve Linear issue** is enabled by default. While it is enabled, select a required **Resolved status**. If you do not want groundcover to transition the Linear issue when the monitor resolves, disable auto-resolve instead.
8. Optionally, select a project, labels, or assignee.
9. Save the route.

<div data-with-frame="true"><figure><img src="/files/TWcOEUPiav17BttaAGhW" alt="Linear connector selected as a notification route destination"><figcaption><p>Send firing and resolved monitor events to the connected Linear workspace.</p></figcaption></figure></div>

When a matching monitor issue fires, groundcover creates one linked Linear issue. Re-notifications add updates to that issue instead of creating duplicates. When the monitor issue resolves, groundcover adds a resolution comment and, when auto-resolve is enabled, moves the Linear issue to the configured resolved status.

For more information about route scopes and rules, see [Notification Routes](/use-groundcover/monitors/notification-routes.md).

## Troubleshooting

### Create App does not open Linear

Allow pop-ups for the groundcover application, then click **Create App** again.

### You cannot create the OAuth application

Ask a Linear workspace administrator to create the application or grant you permission to manage OAuth applications.

### The connector does not appear under My Connections

Confirm that a workspace admin completed the organization connector setup and authorized the intended Linear workspace.

### Linear actions are unavailable

Confirm that the organization connector is still listed under **Org Connectors**. For Agent Mode actions, also confirm that your personal connection is active under **My Connections**.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/connectors/linear.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.