> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Linear Connector Tools
> Connect Genesis to Linear so agents can create, update, search, and comment on issues, upload and download files, manage attachment links, and list teams and projects.
## **Overview**
### **Tool Name**
```json theme={null}
linear_connector_tools
```
### **Purpose**
The **linear\_connector\_tools** group integrates Genesis with Linear issue tracking. It uses the effective usable `linear` connection for the current user and active bot (My default, then Role default) from Genesis Connections and supports both API key and user OAuth authentication.
### **Key Features**
Open new Linear issues, edit fields, assign work, and create sub-issues.
Filter issues by team, assignee, state, project, label, query text, or priority.
Add issue comments and fetch detailed issue or comment history.
Upload files from Git repos or bot storage to Linear, or download files from Linear to bot storage.
Link external URLs to issues, list existing attachment links, or remove them.
List available teams and projects before automating writes.
## **Input Parameters for Each Function**
### **`linear_connector`**
**Core parameters**
| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`action`** | String | none | Required. See the action list below. |
| **`team`** | String | `None` | Linear team name or key such as `Engineering` or `ENG`. Required for `CREATE_ISSUE`; optional filter for `SEARCH_ISSUES` and `GET_PROJECTS`. |
| **`title`** | String | `None` | Issue title for `CREATE_ISSUE` or `UPDATE_ISSUE`. Attachment link title for `CREATE_ATTACHMENT_LINK`. |
| **`description`** | String | `None` | Detailed issue description in Markdown for `CREATE_ISSUE` or `UPDATE_ISSUE`. |
| **`issue_id`** | String | `None` | Linear issue identifier such as `ENG-123` for `GET_ISSUE`, `UPDATE_ISSUE`, `ADD_COMMENT`, `LIST_COMMENTS`, `UPLOAD_FILE`, `LIST_ATTACHMENT_LINKS`, or `CREATE_ATTACHMENT_LINK`. |
| **`assignee`** | String | `None` | Assignee name, email, or `me` for `CREATE_ISSUE`, `UPDATE_ISSUE`, or `SEARCH_ISSUES`. `me` requires a `user_oauth` Linear connection. Use `Unassigned` to clear the assignee on `UPDATE_ISSUE` or filter for unassigned work in `SEARCH_ISSUES`. |
| **`state`** | String | `None` | Workflow state name such as `In Progress` or `Done` for `CREATE_ISSUE`, `UPDATE_ISSUE`, or `SEARCH_ISSUES`. |
| **`priority`** | String | `None` | Priority value for `CREATE_ISSUE`, `UPDATE_ISSUE`, or `SEARCH_ISSUES`: `Urgent`, `High`, `Normal`, `Medium`, `Low`, or `None`. |
| **`project`** | String | `None` | Project name or slug for `CREATE_ISSUE`, `UPDATE_ISSUE`, or `SEARCH_ISSUES`. |
| **`labels`** | Array of strings | `None` | Label names for `CREATE_ISSUE` or `UPDATE_ISSUE`, for example `["bug", "priority-high"]`. |
| **`label`** | String | `None` | Single label name to filter by during `SEARCH_ISSUES`. |
| **`body`** | String | `None` | Comment body in Markdown for `ADD_COMMENT`. |
| **`query`** | String | `None` | Free-text query for `SEARCH_ISSUES`. Genesis matches the text against issue titles and identifiers after other filters are applied. |
| **`parent_id`** | String | `None` | Parent issue identifier such as `ENG-100` for `CREATE_ISSUE` or `UPDATE_ISSUE` to create or move a sub-issue. |
| **`estimate`** | Integer | `None` | Issue estimate value for `CREATE_ISSUE` or `UPDATE_ISSUE`. |
| **`due_date`** | String | `None` | Due date in ISO format such as `2025-12-31` for `CREATE_ISSUE` or `UPDATE_ISSUE`. |
| **`connection`** | String | `None` | Optional Linear connection name such as `linear.work` or `work`. Uses the effective usable `linear` connection for the current user and active bot when omitted. |
**File and attachment link parameters**
| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`file_path`** | String | `None` | Path to a file in a Git repo or bot storage for `UPLOAD_FILE`. |
| **`repo_id`** | String | `None` | Git repository ID for locating files in `UPLOAD_FILE`. |
| **`filename`** | String | `None` | Filename override for `UPLOAD_FILE` or `DOWNLOAD_FILE`. |
| **`comment`** | String | `None` | If provided with `UPLOAD_FILE`, a comment containing a link to the uploaded file is added to the issue. |
| **`url`** | String | `None` | URL for `CREATE_ATTACHMENT_LINK` (the external resource to link) or `DOWNLOAD_FILE` (a Linear asset URL to download). |
| **`attachment_id`** | String | `None` | Attachment link ID for `GET_ATTACHMENT_LINK` or `DELETE_ATTACHMENT_LINK`. |
| **`subtitle`** | String | `None` | Subtitle for `CREATE_ATTACHMENT_LINK`. |
| **`icon_url`** | String | `None` | Icon image URL (PNG or JPG) for `CREATE_ATTACHMENT_LINK`. |
| **`metadata`** | Dict | `None` | Key-value metadata dict for `CREATE_ATTACHMENT_LINK`. |
`thread_id`, `bot_id`, and `user_id` are supplied implicitly by Genesis at runtime, so you normally only provide the business fields above.
**Available actions**
| **Action** | **Description** | **Required parameters** |
| - | - | - |
| `CREATE_ISSUE` | Create a new issue | `team`, `title` |
| `UPDATE_ISSUE` | Update an existing issue | `issue_id` |
| `GET_ISSUE` | Get detailed issue information | `issue_id` |
| `SEARCH_ISSUES` | Search issues with filters | (all optional) |
| `ADD_COMMENT` | Add a comment to an issue | `issue_id`, `body` |
| `LIST_COMMENTS` | List comments on an issue | `issue_id` |
| `UPLOAD_FILE` | Upload a file to Linear cloud storage | `issue_id`, `file_path` |
| `DOWNLOAD_FILE` | Download a file from a Linear asset URL to bot storage | `url` |
| `LIST_ATTACHMENT_LINKS` | List attachment links on an issue | `issue_id` |
| `CREATE_ATTACHMENT_LINK` | Link an external URL to an issue | `issue_id`, `url`, `title` |
| `GET_ATTACHMENT_LINK` | Get attachment link details | `attachment_id` |
| `DELETE_ATTACHMENT_LINK` | Remove an attachment link | `attachment_id` |
| `GET_TEAMS` | List available teams | (none) |
| `GET_PROJECTS` | List projects | (none; optional `team` filter) |
## **Workflow/How It Works**
1. Configure your effective default `linear` connection in [Linear](/docs/Setup/Linear), or pass `connection` when you need a specific saved connection.
2. Start with `GET_TEAMS` or `GET_PROJECTS` if you need valid team keys or project names.
3. Use `CREATE_ISSUE`, `UPDATE_ISSUE`, `GET_ISSUE`, and `SEARCH_ISSUES` to manage work items.
4. Use `ADD_COMMENT` and `LIST_COMMENTS` to collaborate inside an issue thread.
5. Use `UPLOAD_FILE` to attach files (logs, reports, CSVs, images) to issues and `DOWNLOAD_FILE` to pull files from Linear asset URLs into bot storage.
6. Use `CREATE_ATTACHMENT_LINK`, `LIST_ATTACHMENT_LINKS`, `GET_ATTACHMENT_LINK`, and `DELETE_ATTACHMENT_LINK` to manage structured URL references in Linear's Attachments panel.
Do not retry a governed write after `reconciliation_required`; the Action Review
sweep may resolve eligible results as described in the [Action Review response
contract](/docs/Genesis-API/API-Reference#action-review-response-fields).
## **Examples**
```python theme={null}
# List available teams
linear_connector(action="GET_TEAMS")
```
```python theme={null}
# Create a new issue
linear_connector(
action="CREATE_ISSUE",
team="ENG",
title="Investigate elevated API latency",
description="Customer reports repeated timeouts from the sync job.",
assignee="me",
priority="High",
labels=["incident", "api"],
due_date="2026-04-02",
)
```
This example assumes the default `linear` connection uses `user_oauth`. If the default connection uses `api_key`, pass a specific Linear user name or email instead of `assignee="me"`.
```python theme={null}
# Search for active high-priority work
linear_connector(
action="SEARCH_ISSUES",
team="ENG",
state="In Progress",
priority="High",
)
```
```python theme={null}
# Upload a report file to an issue
linear_connector(
action="UPLOAD_FILE",
issue_id="ENG-42",
file_path="reports/latency_analysis.csv",
repo_id="my-repo",
comment="Attached the latency analysis report.",
)
```
```python theme={null}
# Download a file from Linear to bot storage
linear_connector(
action="DOWNLOAD_FILE",
url="https://uploads.linear.app/asset123.csv",
filename="latency_report.csv",
)
```
```python theme={null}
# Link an external resource to an issue
linear_connector(
action="CREATE_ATTACHMENT_LINK",
issue_id="ENG-42",
url="https://grafana.example.com/dashboard/latency",
title="Grafana Dashboard",
subtitle="API Latency",
)
```
```python theme={null}
# List attachment links on an issue
linear_connector(action="LIST_ATTACHMENT_LINKS", issue_id="ENG-42")
```
## **Output**
* `CREATE_ISSUE`, `UPDATE_ISSUE`, and `SEARCH_ISSUES` return compact issue records with `id`, `title`, `url`, `state`, `assignee`, `priority`, `project`, `team`, and `labels`.
* `GET_ISSUE` returns a detailed issue object with description, creator, estimate, due date, parent, children, `attachments`, and timestamps.
* `ADD_COMMENT` returns the created comment metadata.
* `LIST_COMMENTS`, `GET_TEAMS`, and `GET_PROJECTS` return `count` plus an array of results.
* Comment records include `author` and, where available, `author_email`; either field can be `null` when Linear does not return a user for the comment.
* `UPLOAD_FILE` returns `asset_url`, `filename`, `size`, and `content_type`. If `comment` was provided, includes the created comment.
* `DOWNLOAD_FILE` returns `filename`, `file_path`, `relative_path`, `file_id`, and `size`.
* `LIST_ATTACHMENT_LINKS` returns `count` plus an array of attachment link details.
* `CREATE_ATTACHMENT_LINK` returns the created attachment link with `id`, `title`, `subtitle`, and `url`.
* `GET_ATTACHMENT_LINK` returns full attachment link details including the associated issue and creator.
* `DELETE_ATTACHMENT_LINK` returns `success`.
## **Configuration Details**
* The tool resolves the effective usable `linear` connection for the current user and active bot (My default, then Role default). Pass `connection` to target a specific saved connection instead.
* Genesis supports both `api_key` and `user_oauth` authentication for Linear.
* Connection tests query `https://api.linear.app/graphql` and verify the authenticated `viewer`.
* For `user_oauth`, Genesis uses fixed provider endpoints: `https://linear.app/oauth/authorize` and `https://api.linear.app/oauth/token`.
* If your deployment restricts outbound access, allow both `linear.app` and `api.linear.app`.
## **Limitations or Notes**
1. `SEARCH_ISSUES` text matching is limited to issue titles and identifiers, and each call returns up to 50 issues.
2. Unknown label names cause `CREATE_ISSUE` or `UPDATE_ISSUE` to fail; Genesis does not create labels automatically.
3. `assignee="me"` is only supported when the resolved `linear` connection uses `user_oauth`.
4. When multiple role defaults for `linear` conflict, Genesis returns an error directing you to set a user default or pass `connection` explicitly. See [Default connection layers](/docs/Setup/Connections#default-connection-layers).
5. `issue_id` can be a Linear UUID or an issue identifier such as `ENG-123`.
6. A missing or expired OAuth token prevents the tool from connecting until the user reauthorizes.
7. `UPLOAD_FILE` uploads binary files to Linear's cloud storage (via a signed URL). Use this when you have actual file content. `CREATE_ATTACHMENT_LINK` only links a URL; it does not upload files.
8. Files in Linear's private cloud storage require authentication to access externally. `DOWNLOAD_FILE` handles this automatically, but only for HTTPS URLs on supported Linear asset hosts such as `uploads.linear.app`, `cdn.linear.app`, or `api.linear.app`.