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

# Linear

> Connect Linear so an agent can pick up work from issues, process attached files, and comment back.

Connecting Linear lets an agent pick up work from your tickets. Someone files an issue, tags it, and the agent handles it: reading attached files, doing the work, and commenting back on the issue.

Any agent can have Linear triggers, scoped to the teams, labels, or projects it should care about, so one Linear workspace can feed several agents, each with its own instructions and permissions.

## Connecting Linear

In **Workspace settings**, open the **AI** page, choose Linear under Integrations, and complete the authorization.

| Requirement   | Detail                            |
| :------------ | :-------------------------------- |
| In Conversion | Permission to manage integrations |
| In Linear     | A workspace admin                 |

Conversion asks to read issues and comments, post comments, and update issue status. The agent appears in Linear as its own app user, so its comments are clearly attributable rather than posted as whoever connected it.

A Conversion workspace connects to one Linear workspace, and connecting a different one replaces it. You do this once, and then configure individual agents in Conversion.

### Which teams the agent can see

Team access is set in Linear, not in Conversion, and it starts at **all public teams**, so issues in a private team reach nobody until you say otherwise. Nothing happens and no error is raised, which makes it an easy one to lose time on.

A Linear workspace admin changes it:

1. In Linear, go to **Settings → Applications**.
2. Open **Conversion Agent**.
3. Under **Team access**, choose a scope, name the teams, and press **Update**.

| Scope                                        | What it covers                                               |
| :------------------------------------------- | :----------------------------------------------------------- |
| **All public teams**                         | The starting point. Private teams are excluded.              |
| **All public teams and select other teams…** | Every public team, plus the private ones you name.           |
| **Only select teams…**                       | Just the teams you name, private or not. The tightest scope. |

<Tip>
  **Only select teams** is the one to reach for. It keeps the agent out of teams that never wanted it, and it's the only option that covers a private team without also opening up every public one.
</Tip>

This is separate from an agent's [trigger filters](#filters). Team access decides which issues Linear will tell us about at all; filters decide which of those a given agent picks up.

***

## Choosing which issues an agent picks up

A Linear trigger has an event type and, optionally, filters.

### Event types

| Event             | Fires when                   |
| :---------------- | :--------------------------- |
| **Issue created** | A new issue is filed         |
| **Issue updated** | An issue changes             |
| **Comment added** | Someone comments on an issue |

**Comment added** is usually the best choice. It only fires when a person deliberately comments, and the same trigger handles their follow-up messages later in the conversation, including a simple "go ahead" after the agent has shown you its work.

**Issue created** fires once, at creation. Use it only if the label and any files are guaranteed to be there the moment the issue is filed.

<Warning>
  **Issue updated** fires on *every* edit: retitling, moving, tweaking the description. Each one interrupts whatever the agent was doing. Avoid it unless you specifically want that.
</Warning>

### Filters

Filters narrow which issues the agent cares about. Without them, it responds to every issue in the workspace.

| Filter       | Narrows to                                 |
| :----------- | :----------------------------------------- |
| **Team**     | Issues on the teams you pick               |
| **Project**  | Issues in the projects you pick            |
| **Label**    | Issues carrying any of the labels you pick |
| **Status**   | Issues in the workflow states you pick     |
| **Priority** | Urgent, High, Medium, Low, or No priority  |
| **Assignee** | Issues assigned to the people you pick     |

A filter selects specific things in your Linear workspace (this team, these two labels) rather than matching on how they're spelled. Labels, projects, and workflow states each belong to a team in Linear, so a filter on a team also narrows which of them are worth choosing.

All the filters you set must match; within one filter, any value you picked matches. So label `Bug` or `Urgent`, **and** team Engineering.

<Tip>
  A dedicated label is the clearest way to scope an agent. Make a label like `conversion-agent`, filter on it, and the agent picks up exactly the issues someone deliberately tagged.
</Tip>

<Warning>
  **Renaming is safe, deleting isn't.** Because a filter points at the thing itself, renaming a label, project, or workflow state in Linear leaves your triggers working.

  Deleting one leaves a filter that can never match, so the agent quietly stops firing, with no error. Check an agent's triggers after tidying up in Linear.
</Warning>

***

## Working with files

Files attached to an issue, or to a comment on it, are available to the agent. It can read spreadsheets and CSVs, transform them, and produce new files for you to download. See [Files and sandbox](/product-docs/conversion-ai/files-and-sandbox).

This is the core of the pattern: someone attaches a partner file to a ticket, tags it, and the agent does the processing that used to be manual.

## What the agent writes back

| Action            | Scope                        |
| :---------------- | :--------------------------- |
| **Comment**       | On the triggering issue only |
| **Update status** | On the triggering issue only |

Both are locked to the issue that started the session. An agent can't comment on or move a different ticket, even if asked to, so an agent scoped to one label can never touch issues outside it.

***

## Several agents, one issue

Each agent with a matching trigger gets its own session on the same issue. Three agents can work one ticket independently, each with its own conversation and its own comments.

Later comments reach all of them, because a comment always names the issue it's on. If you'd rather one agent handled a given kind of ticket, scope them with different labels.

***

## Things to know

### It won't reply to itself

The agent's own comments and status changes don't wake it up.

### Pausing doesn't stop an issue it's already on

An agent already working an issue keeps responding to new comments there, even paused, because a linked issue accepts the comment without checking triggers. To stop that, delete the agent or disconnect Linear. See [Triggers](/product-docs/conversion-ai/agents/triggers#pausing-an-agent).

### Filters are checked when the agent joins, not on every comment

If an issue's status or labels change after the agent has picked it up, it carries on regardless.

***

## Related

<Columns cols={2}>
  <Card title="Agents overview" icon="robot" href="/product-docs/conversion-ai/agents/overview">
    What an agent is and what you configure on it.
  </Card>

  <Card title="Files and sandbox" icon="folder" href="/product-docs/conversion-ai/files-and-sandbox">
    What an agent can do with an attached file.
  </Card>
</Columns>