# Connect EMQX Agents to Linear

The Linear connector lets EMQX Agents create, search, read, and update issues, projects, and comments. It also provides teams, users, labels, and workflow states as context for project automation.

## Common Use Cases

- Create an issue from an MQTT alert or Fleets event.
- Summarize issues in a team or project.
- Update an issue state after an automated check.
- Add an analysis result as a comment on an issue.

Example chat prompt:

```text
Use the engineering-linear connector to create an issue in the IoT team for the repeated disconnect alert. Include the device ID and the last five error messages.
```

## Prerequisites

Before adding the connector, prepare:

- A Linear account. If the account does not have a workspace, you can create one during authorization.
- Permission to grant Composio admin, read, and write access to the Linear workspace.
- Access to the teams and projects required by the workflow.

## Add a Linear Connector

1. In the left navigation menu, click **Connectors**.
2. On the **Available** tab, locate **Linear** and click **Add**.
3. Enter a descriptive connector name.
4. Click **Confirm**. The Linear authorization flow opens in a dialog.

If your Linear account already has a workspace, continue to [Authorize Composio](#authorize-composio). Otherwise, create a workspace before completing the authorization.

### Create a Linear Workspace If Required

1. On the **Create a workspace** page, enter the workspace **Name** and review or edit its **URL**.
2. Select **United States** or **European Union** from the **Region** list.
3. Click **Create workspace**.
4. [Optional] Invite teammates or click **Skip**.
5. [Optional] Connect GitHub or click **Skip**.
6. [Optional] Connect Slack or click **Skip**.
7. Select any update subscriptions that you want to receive, then click **Finish**.

The teammate invitations, GitHub connection, Slack connection, and update subscriptions are part of Linear onboarding and are not required to authorize the EMQX Agents connector.

### Authorize Composio

1. On the authorization page, select the workspace to connect from the workspace list.
2. Review the access requested by Composio. The authorization grants:
   - Admin access to manage workspace settings and people.
   - Read access to the workspace.
   - Write access to the workspace.
3. Click **Authorize**.
4. Wait for the authorization dialog to close and return to EMQX Agents.
5. On the **Added** tab, verify that the connector status is **Authorized**.

## Supported Tools

### Create and Update Resources

| Tool | Access | Description |
|---|---|---|
| `LINEAR_CREATE_LINEAR_COMMENT` | Write | Creates a comment on a Linear issue. |
| `LINEAR_CREATE_LINEAR_ISSUE` | Write | Creates a Linear issue. |
| `LINEAR_CREATE_LINEAR_PROJECT` | Write | Creates a Linear project. |
| `LINEAR_REMOVE_ISSUE_LABEL` | Write | Removes a label from an issue. |
| `LINEAR_RESOLVE_COMMENT` | Write | Marks a Linear comment as resolved. |
| `LINEAR_UPDATE_ISSUE` | Write | Updates a Linear issue. |
| `LINEAR_UPDATE_LINEAR_COMMENT` | Write | Updates a Linear comment. |

### Read and Search Resources

| Tool | Access | Description |
|---|---|---|
| `LINEAR_GET_COMMENT` | Read | Gets a Linear comment. |
| `LINEAR_GET_CURRENT_USER` | Read | Gets the currently authorized Linear user. |
| `LINEAR_GET_LINEAR_ISSUE` | Read | Gets a Linear issue. |
| `LINEAR_GET_LINEAR_PROJECT` | Read | Gets a Linear project. |
| `LINEAR_LIST_COMMENTS` | Read | Lists Linear comments. |
| `LINEAR_LIST_ISSUES_BY_TEAM_ID` | Read | Lists issues for a team. |
| `LINEAR_LIST_LINEAR_ISSUES` | Read | Lists Linear issues. |
| `LINEAR_LIST_LINEAR_LABELS` | Read | Lists Linear labels. |
| `LINEAR_LIST_LINEAR_PROJECTS` | Read | Lists Linear projects. |
| `LINEAR_LIST_LINEAR_STATES` | Read | Lists Linear workflow states. |
| `LINEAR_LIST_LINEAR_TEAMS` | Read | Lists Linear teams. |
| `LINEAR_LIST_LINEAR_USERS` | Read | Lists Linear users. |
| `LINEAR_SEARCH_ISSUES` | Read | Searches Linear issues. |

::: warning Important Notice
Issue updates, label removal, and comment resolution change project records. Confirm the target issue, project, and team before write operations.
:::

## Use the Connector in a Chat

1. In the chat input area, click the connector icon.
2. Select the authorized **Linear** connector.
3. In the prompt, identify the external resource and operation that the agent should use.
4. Review the generated agent definition and confirm that it contains only the required tools.

## Permissions and Data Access

The connector uses the authorized Linear account. Workspace membership, team access, and Linear roles determine which issues and projects the connector can read or modify.

Do not include external service credentials or access tokens in the chat prompt or agent instructions.

## Limitations

- Linear API quotas and workspace policies apply.
- Issue creation and updates require access to the target team.
- Available workflow states and labels depend on the selected workspace and team.

<!-- TODO: Confirm service-specific result size limits, file limits, API rate limits, plan restrictions, and unsupported resource types. -->

## Troubleshooting

| Symptom | Resolution |
|---|---|
| The connector remains **Unauthorized**. | Complete the Linear workspace setup if required, select the intended workspace, and click **Authorize**. |
| A tool returns a permission error. | Verify that the authorized Linear account has access to the target workspace, team, or project and can grant the required workspace permissions. Reauthorize the connector if necessary. |
| A required tool is unavailable. | Verify that the tool is supported and approved for this connector, then select the connector again in the chat. |
| Requests are rejected intermittently. | Check the external service status, API quota, rate limits, and account plan. |

## Related Links

- [Connectors](../connectors.md)
- [Start a Chat](../chats.md)
- [Manage Agents](../agents.md)