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

# Connect your Linear workspace and issues to AgentRail

> Link Linear to AgentRail to import issues and route them to the right agent. Covers connection setup, import by identifier or URL, and routing behavior.

Connecting Linear to AgentRail lets you import Linear issues directly into the AgentRail task lifecycle. Once imported, issues go through the routing engine, which evaluates your configured routing rules to assign the task to the right agent. Run `agentrail provider connect linear` to set this up.

## Connect Linear

```bash theme={null}
agentrail provider connect linear
```

The interactive setup prompts for your Linear API key in a hidden prompt, validates credentials, runs provider readiness checks, and reports any blockers it cannot resolve automatically.

<Note>
  For non-interactive environments such as CI pipelines, set the `LINEAR_API_KEY` environment variable before running the connect command.

  ```bash theme={null}
  export LINEAR_API_KEY=lin_api_...
  agentrail provider connect linear
  ```
</Note>

## Import a Linear issue

After connecting, import issues into AgentRail using the identifier, full Linear URL, or UUID:

<CodeGroup>
  ```bash By identifier theme={null}
  agentrail linear import ENG-123
  ```

  ```bash By URL theme={null}
  agentrail linear import https://linear.app/your-org/issue/ENG-123
  ```

  ```bash By UUID theme={null}
  agentrail linear import 9a3f1b2c-...
  ```
</CodeGroup>

AgentRail fetches the issue from Linear, normalizes it into an AgentRail task candidate, and passes it through the routing engine.

## How routing works

Imported issues do not automatically become assigned tasks. They go through AgentRail's routing engine, which evaluates your configured routing rules to decide which agent should handle the work.

<Warning>
  If routing is not configured, AgentRail fails closed. It does not create hidden unassigned work. Set up routing rules before importing issues to ensure they are assigned correctly.
</Warning>

To configure routing, run `agentrail init` and follow the routing setup prompts, or use `agentrail agent create` to add a routing rule for a specific agent.

## Verify the connection

Check the health of your Linear connection:

```bash theme={null}
agentrail provider doctor linear
```

You can also check all connected providers at once:

```bash theme={null}
agentrail provider status
agentrail provider doctor
```

## Troubleshooting

| Symptom                        | Likely cause                                    | Fix                                                                                       |
| ------------------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Imported issue is not assigned | Routing is not configured                       | Run `agentrail init` or `agentrail agent create` to create a routing rule, then reimport. |
| `401` or credential error      | `LINEAR_API_KEY` is missing or invalid          | Confirm the key is set and re-run `agentrail provider connect linear`.                    |
| Import command returns no task | Issue already imported or routing failed closed | Check routing config with `agentrail doctor` and inspect routing audit records.           |