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

# Linear

> Connect Linear with Qontext

## Overview

The Linear connection lets Qontext read issues, projects, and documents from your Linear workspace and sync them into your context repository. Each record becomes a structured text document (its key fields together with the discussion around it) so your agents can retrieve the planning context behind your product: what is being built, why, where it stands, and what was said about it. Qontext connects to Linear through the GraphQL API over OAuth.

<Info>
  Qontext only reads data; it never creates, edits, or deletes anything in Linear. Access is always bounded by the connected user's own Linear permissions, so Qontext can only sync what that account can already see.
</Info>

**Supported objects:**

| Object            | Description                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| `Issues`          | Issues with their title, description, state, priority, assignee, labels, Linear team, and project |
| `Comments`        | Issue comment threads, synced inline as part of their issue rather than as separate records       |
| `Projects`        | Projects with their short description, full markdown overview, status, lead, and target date      |
| `Project updates` | The status narrative posted against a project over time, synced inline as part of their project   |
| `Documents`       | Standalone Linear documents (PRDs, specs, RFCs) attached to a project, a Linear team, or an issue |

**Unsupported:**

| Object                             | Description                                                                                                                                                |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Initiatives`                      | The org-level grouping above projects. Not synced, and documents attached to an initiative are excluded as well                                            |
| `Cycles`                           | A cycle carries only a name and a date range; the issues inside it are already synced                                                                      |
| `Linear teams, users, and labels`  | Available as filter options and as metadata on synced issues, but not synced as records of their own                                                       |
| `Attachments and embedded uploads` | Files hosted on `uploads.linear.app` require an authenticated fetch. Their links are preserved in the synced text, but the files themselves are not synced |
| `Emoji reactions`                  | No content value                                                                                                                                           |

***

## Recommended setup

Use a **dedicated integration user** in your Linear workspace to ensure a stable and uninterrupted connection.

<div className="qontext-tip-check-wrapper">
  <Tip>Create a service account such as `qontext@yourcompany.com`, add it to your Linear workspace, and give it access to the Linear teams you want Qontext to sync. This prevents sync disruptions when employee accounts or permissions change.</Tip>
</div>

The integration user will:

* Authenticate the connection between Qontext and Linear.
* Access the selected issues, projects, and documents with read-only permissions.

<Info>
  Qontext requests a single Linear scope, `read`, and uses OAuth with PKCE. It deliberately does not request `admin`, which Linear only requires for managing webhooks.
</Info>

***

## Setting up the connection

You can connect Linear from your Qontext workspace, authorize access with your Linear account, then choose what to sync and how often. Linear needs no workspace URL or subdomain, so authorizing is a single step.

<Info>
  You can also manage all your credentials, including Linear, from the **Sources** page.
</Info>

<Steps>
  <Step title="Open Sources in your workspace">
    In the [Qontext app](https://app.qontext.ai), open your workspace and go to the **Sources** tab, then click **+ Connect data source**.
  </Step>

  <Step title="Select Linear as the data source">
    Choose **Linear** from the list of available data sources. This starts the Linear connection flow.
  </Step>

  <Step title="Connect your Linear account">
    You can **reuse existing Linear credentials** (if you have already connected this account to Qontext) or **create a new connection**.

    If you create a new credential, sign in with Linear when prompted. On the consent screen, review the requested access and authorize Qontext to read your workspace.
  </Step>

  <Step title="Configure what to sync (filters)" id="configure-what-to-sync-filters">
    Choose which projects, issues, and documents Qontext should sync into your context repository. By default all three are included and scoped to everything in the workspace.

    See [Filtering what gets synced](#filtering-what-gets-synced) below for the full set of options.
  </Step>

  <Step title="Set sync frequency">
    Choose how often Qontext should refresh data from Linear (e.g. daily, weekly, monthly). More frequent syncs keep the context repository up to date but use more resources.
  </Step>

  <Step title="Review and create connection">
    Review your choices (workspace, selection, frequency), then confirm to create the connection. Qontext will start the initial sync shortly after.
  </Step>
</Steps>

***

## Filtering what gets synced

Linear filters are organized as three independent rules: one for **projects**, one for **issues**, and one for **documents**. Each rule can be switched off entirely, and each carries its own scope, because the same word means different things per content type. An issue belongs to exactly one Linear team, a project can span several, and a document hangs off whichever container it was created in.

By default all three rules are on and set to sync everything.

<AccordionGroup>
  <Accordion title="Projects: all, filtered, or specific">
    * **All**: every project in the workspace.
    * **Filtered**: narrow by Linear team, by status (Backlog, Planned, In Progress, Paused, Completed, Canceled), by project label, by project lead, and by last-updated date.
    * **Specific**: hand-pick individual projects.
  </Accordion>

  <Accordion title="Issues: all, by team, or from included projects">
    * **All**: every issue in the workspace.
    * **By team**: only issues belonging to the Linear teams you select.
    * **From included projects**: only issues belonging to the projects your Projects rule already includes, so the two selections stay consistent.

    An issue does not have to belong to a project, and in most workspaces many do not. The **From included projects** mode therefore also offers a checkbox to **include issues without a project**, which adds those back.
  </Accordion>

  <Accordion title="Issue filters that apply in every mode">
    Whichever scope you pick, issues can be narrowed further by state (Triage, Backlog, Todo, In Progress, Done, Canceled), by issue label, by assignee, and by last-updated date.

    <Info>
      Issue labels and project labels are separate things in Linear, so they are chosen in separate pickers and cannot be used interchangeably.
    </Info>
  </Accordion>

  <Accordion title="Documents: all, or only those attached to included content">
    * **All**: every document in the workspace, whether it is attached to a project, a Linear team, or an issue.
    * **From included projects and issues**: only documents attached to a project or an issue that is already in scope, which keeps your documents aligned with the rest of the selection.

    Documents can also be limited by last-updated date. Documents attached to an initiative are not synced in either mode.
  </Accordion>
</AccordionGroup>

***

## Sync latency

The initial sync time depends on how many issues, projects, and documents are in scope. Large workspaces can take **up to 6 hours** to fully sync.

<Info>
  Subsequent syncs are **incremental**: Qontext processes only the records that were added or changed since the last sync, which runs much faster than the initial sync.
</Info>

***

## Managing permissions

### Linear OAuth scope

When connecting, you authorize Qontext against your Linear workspace. Qontext requests one scope:

```text theme={null}
- read   Read the workspace data the connected user can already see
```

Qontext uses this access only to **read**. It never creates, edits, or deletes anything in Linear, and because `read` operates as the connected user, Qontext can only ever see what that account can see.

### Linear permissions

* Use a **single integration user** to manage Linear access for Qontext to avoid permission conflicts.
* If a project, Linear team, or document does not appear during filter setup, check that the connected account has access to it in Linear.
* Linear access tokens are short-lived, and Qontext refreshes them automatically in the background. If a refresh is rejected, for example because the authorization was revoked in Linear, the connection stops syncing and prompts you to reconnect it from the **Sources** tab.

***

## FAQ

<AccordionGroup>
  <Accordion title="Who can set up the Linear connection?">
    Any workspace member with a Linear account that has access to the relevant content. Qontext syncs exactly what that account can see, so an account with access to every Linear team gives the most complete result.
  </Accordion>

  <Accordion title="Does Qontext write anything back to Linear?">
    No. Qontext only reads issues, projects, and documents. It never creates, edits, or deletes data in Linear, and it never comments on an issue.
  </Accordion>

  <Accordion title="Are issues that do not belong to a project synced?">
    Yes, by default. An issue in Linear belongs to exactly one Linear team but does not need a project. If you scope issues to **From included projects**, use the **include issues without a project** checkbox to keep those issues in scope.
  </Accordion>

  <Accordion title="Are comments and project updates retrievable on their own?">
    They are retrievable as part of the record they belong to. A comment thread is synced with its issue, and project updates are synced with their project, so agents read the discussion in the context that gives it meaning rather than as a detached fragment.
  </Accordion>

  <Accordion title="Can I connect multiple Linear workspaces?">
    Yes. You can create multiple Linear connections from the **Sources** tab in your Qontext workspace. Add each Linear workspace as a separate data source.
  </Accordion>

  <Accordion title="How do I manually refresh Linear data?">
    Manual refresh is available via the **Sources** tab. Navigate to the respective Linear connection and open the **Syncs** tab. In the sync settings, you can select **Resync all data**.
  </Accordion>

  <Accordion title="What happens if I disconnect Linear?">
    Disconnecting stops further syncs. Content already synced from Linear remains in your context repository. For data removal, contact [support@qontext.ai](mailto:support@qontext.ai).
  </Accordion>

  <Accordion title="How can I limit what Qontext accesses?">
    By default, Qontext only syncs content the connected Linear account can access. Additionally, you can add [filters](#configure-what-to-sync-filters) to every connection as described in the setup flow.
  </Accordion>
</AccordionGroup>