Linear Connector Tools - Genesis Computing

Overview

Tool Name

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

Create and update issues

Open new Linear issues, edit fields, assign work, and create sub-issues.

Search active work

Filter issues by team, assignee, state, project, label, query text, or priority.

Comment and review context

Add issue comments and fetch detailed issue or comment history.

Upload and download files

Upload files from Git repos or bot storage to Linear, or download files from Linear to bot storage.

Manage attachment links

Link external URLs to issues, list existing attachment links, or remove them.

Discover teams and projects

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

Configure your effective default linear connection in Linear, or pass connection when you need a specific saved connection.
Start with GET_TEAMS or GET_PROJECTS if you need valid team keys or project names.
Use CREATE_ISSUE, UPDATE_ISSUE, GET_ISSUE, and SEARCH_ISSUES to manage work items.
Use ADD_COMMENT and LIST_COMMENTS to collaborate inside an issue thread.
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.
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.

Examples

# List available teams
linear_connector(action="GET_TEAMS")

# 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".

# Search for active high-priority work
linear_connector(
    action="SEARCH_ISSUES",
    team="ENG",
    state="In Progress",
    priority="High",
)

# 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.",
)

# Download a file from Linear to bot storage
linear_connector(
    action="DOWNLOAD_FILE",
    url="https://uploads.linear.app/asset123.csv",
    filename="latency_report.csv",
)

# 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",
)

# 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

SEARCH_ISSUES text matching is limited to issue titles and identifiers, and each call returns up to 50 issues.
Unknown label names cause CREATE_ISSUE or UPDATE_ISSUE to fail; Genesis does not create labels automatically.
assignee="me" is only supported when the resolved linear connection uses user_oauth.
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.
issue_id can be a Linear UUID or an issue identifier such as ENG-123.
A missing or expired OAuth token prevents the tool from connecting until the user reauthorizes.
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.
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.