> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Connect Linear to your factory

Connect Linear to a factory so issues, comments, and agent sessions start factory work and receive progress and pull request updates.

Connect Linear to your factory so the issues your team already tracks can start factory work, and progress flows back to those issues. Two parts work together:

-   **The Linear connection** - Grants Warp access to your Linear workspace.
-   **Factory automations** - Decide which Linear events start work and which agent handles them.

## Prerequisites

-   **A factory** - Create a factory with the agents, repositories, and environment needed to handle Linear work.
-   **A Linear workspace** - Use a Linear account that can authorize the Warp app for the workspace.
-   **A linked Warp account, for agent sessions** - Anyone who starts a Linear agent session must link their Linear user to their Warp account. If Warp can’t identify the session creator, Linear shows an authentication prompt instead of starting work.
-   **Code host access** - Configure repository credentials separately. The factory needs them to change code or create a pull request.

For installation, reconnection, and removal steps, see the [Linear integration setup guide](../../platform/integrations/linear).

## Connect and configure Linear

1.  In your factory setup, open **Connect your issue trackers**. On the **Linear** row, click **Connect**.
2.  Complete Linear’s OAuth flow for the workspace you want. The connection is now active.
3.  Under **Linear team**, select the teams that should trigger your factory.
4.  In the factory’s automation editor, click **Add trigger** > **Linear**, then choose an event: **Issue created**, **Issue labeled**, **Issue state changed**, **Issue assigned**, or **Comment created**.
5.  Select teams and labels to filter on. Click **More filters** to also filter by project, workflow state, assignee, mentioned user, or, for comment events, a specific issue. Then choose the agent that receives the work, add any instructions, and save.

Filters control when a trigger fires. An empty filter matches everything in the connected workspace, and every filter you add must match. For example, a trigger can require that an issue belongs to one team, enters a selected workflow state, and carries a release label.

Caution

Team selections and filters only route events. They don’t reduce what the connection is allowed to access; the OAuth flow sets the workspace and teams Warp can reach.

### Route agent sessions

A Linear agent session starts when a user mentions, assigns, or delegates the Warp app on an issue. Selecting teams during setup creates a default automation that routes new sessions from those teams to your factory. If a session doesn’t match any automation, the [Linear integration](../../platform/integrations/linear) handles it with its default behavior.

Agent sessions don’t appear as a trigger in the automation editor. To change how sessions route, for example by creator or keyword, edit the `agent_session_created` event in the factory’s [version-controlled definition](../factory-as-code). Replies in an existing session continue that run; they aren’t separate triggers.

## Supported events and outputs

Issue and comment events start work only when they match an enabled automation.

| Linear event | What the agent receives | What the factory sends back |
| --- | --- | --- |
| Issue created, labeled, state changed, or assigned | The issue’s title, description, team, project, labels, workflow state, and assignee | Work item progress, issue state or delegate changes, and links to results |
| Comment created | The new comment and its issue’s context | An acknowledgment, progress updates, and responses |
| Agent session created | The request that mentioned, assigned, or delegated the Warp app | Live progress in the session, plus links to the run and any pull request |
| Reply in an agent session | The new message and the session history | Continued work in the same session, not a separate work item |

## Follow-up events on the same issue

Once a Linear issue is linked to a factory work item, later matching events on that issue continue the same work item instead of creating a new one.

Caution

One comment can match two routes: a comment that creates an agent session can also match a **Comment created** trigger. If both point at your factory, a single action starts two runs. Scope your automations so one path owns each kind of request.

## What the factory can do in Linear

In an agent session, the factory posts its plan, actions, and results as it works. It can also attach a GitHub pull request to the issue, update the issue’s workflow state or delegate, link back to the run, and acknowledge comments it acts on.

The factory’s own Linear activity never triggers automations, so its updates can’t start a loop of new runs.

Only agent sessions require a linked Warp account. Issue and comment events from unlinked users still start work, but Warp may not record who requested it.

The Linear connection doesn’t grant repository access or merge permissions. Code-host credentials control branches and pull requests, and human review and merge requirements still come from your factory workflow and repository settings.

## Troubleshooting

-   **An agent session shows an authentication prompt** - Complete the prompt to link your Linear user to your Warp account, then retry the request.
-   **Teams or filters don’t load** - Reconnect Linear from the [integration setup](../../platform/integrations/linear), then confirm the connection can access the workspace and team you expect.
-   **An event doesn’t start work** - Confirm the automation is enabled, the event type matches, and every filter matches the issue’s current values or the state change.
-   **One action starts multiple runs** - Look for overlapping agent-session and comment triggers, then narrow or remove one.
-   **No pull request appears** - Check the factory’s code-host credentials and repository access. Linear authorization alone doesn’t allow code changes.