Skip to main content
connic
Connectors

Linear

Start agents from issues and comments in a Linear team, and post their results as comments or new issues.

Last updated
ModesInbound, outbound
YAML typelinear
CredentialsA Connection of type linear, with a personal Linear API key
BridgeNot supported
Custom domainNot supported
Linked agentsOne or more. A matching event starts every linked agent.
While pausedEvents get 200 and start no runs. Outbound sends nothing.

Set up

  1. In Linear, open Settings → Account → Security & Access and create a personal API key. For inbound connectors, create it as a workspace admin, since connic registers a webhook for the team. Connectors act as the key's member; see API key and member.

  2. In connic, open Project Settings → Connections, click New connection, and choose Linear. You can also create the Connection from the Connection picker in the connector form. Enter a Name, paste the key under API key, and click Create connection. connic checks the key with Linear.

  3. Open the agent. In Connector Flow, click Add inbound connector for issue and comment events or Add outbound connector for comments and issues. Then click Create New Connector and choose Linear.

  4. Choose the mode, Inbound (Team events) or Outbound (Comments and issues), and pick the Connection under Connection. Enter the Team by its key, the prefix of its issue IDs, such as ENG, and for inbound the Events. Click Create. An inbound connector registers its webhook in Linear now. For outbound, then choose how the agent uses the connector and click Link connector.

Configuration

The fields of a Linear connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.

FieldTypeStatusDescription
typestringRequiredlinear.
modestringRequiredinbound or outbound. Dashboard: Mode.
connectionstringRequiredInbound and outbound. Name or ID of a Linear Connection. Dashboard: Connection.
configobjectRequiredLinear settings.
teamstringRequiredInbound and outbound. The team's key, the prefix of its issue IDs, such as ENG. Inbound connectors receive its events, and outbound connectors create issues there. The team must be in the API key's workspace, and for a private team the key's member must belong to it. Dashboard: Team.
eventsstring[]RequiredInbound. The events that start runs. Each entry is Issue or Comment for created and updated ones, or one of Issue.create, Issue.update, Comment.create, and Comment.update for one action only. Dashboard: Events, one per line, starting with Issue.create and Comment.create.

The API key belongs to the Connection, not to the connector.

Generated values

connic sets these when you save the connector or its Connection.

ValueModesDescription
WebhookInboundThe connector's webhook in Linear, with a signing secret connic generates. connic registers it when you save the connector, so you don't create it in Linear.
Team IDInbound, outboundLinear's ID of the team you enter by its key.
Member and workspaceInbound, outboundThe member the API key belongs to and the workspace's name, stored on the Connection when you save it.

Agent input

Modes: Inbound

An inbound connector starts a run for every linked agent each time an issue or comment in its team is created or updated and matches its events. The run receives:

payload.json
{
  "event": "Comment",
  "action": "create",
  "issue": "ENG-42",
  "conversation_id": "linear:9b2f4c1e-6d3a-4f8b-a1c7-2e5d8f0b3a64",
  "title": "Checkout fails for EUR orders",
  "text": "Still happening after the last deploy.",
  "url": "https://linear.app/acme/issue/ENG-42/checkout-fails-for-eur-orders#comment-5d1a2c3b",
  "actor": "Jane Doe",
  "raw": { ... }
}
  • event and action are Issue or Comment, and create or update.
  • issue is the issue's ID, such as ENG-42, and title its title, also for comments.
  • conversation_id stays the same for every event of one issue. To give the agent the earlier comments as history, set session.key: input.conversation_id in its YAML; the connector doesn't turn on sessions by itself.
  • text is the issue's description or the comment, in Markdown, and url the link to it.
  • actor is the name of the person who caused the event.
  • raw is Linear's full webhook payload as sent.

Comments on project updates and other comments outside an issue start no runs. An event that Linear delivers again with the same delivery ID doesn't start another run. Inbound mode doesn't reply by itself: to comment on the issue, link the agent to an outbound Linear connector that uses the same Connection; see Outbound delivery.

API key and member

A personal API key acts as the Linear member who created it. Comments and issues from your agents show that member as their author, and events that member causes are ignored, so agents don't trigger themselves on their own comments. If the key belongs to a person, that person's own changes start no runs either. A Linear member just for your agents avoids that.

Linear only lets workspace admins create webhooks, so an inbound connector needs an admin's key. If you limit the key's permissions or teams in Linear, keep the team and what the connector does: creating webhooks for inbound connectors, comments and issues for outbound ones. Admins decide in Linear whether members may create API keys at all.

Linear webhook

Modes: Inbound

Saving an inbound connector registers a webhook named connic for its team in Linear, for issues, comments, or both, as its events need. Each connector has its own webhook, so several connectors can watch the same team, for example one per environment. You find the webhooks in Linear under Settings → Administration → API.

connic checks the signature of every delivery with the webhook's secret and rejects deliveries Linear sent more than a minute earlier. Changing the team, the Connection, or whether the connector receives issues or comments registers a new webhook and removes the old one. Deleting the connector removes its webhook.

Outbound delivery

Modes: Outbound

An outbound Linear connector posts once each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage. The first rule that applies decides where:

  1. When the output or payload sets issue_id, such as ENG-42, it comments on that issue.
  2. When the run came in through a Linear inbound connector on the same Connection, it comments on the issue the run started from. When a comment started the run, the reply goes into that comment's thread.
  3. Otherwise it creates an issue in the connector's team. The title is title from the output or payload, or else the first line of the text, and the text becomes the description.

Automatic output

An automatic link posts the run's final output. Plain text becomes the text. A JSON object takes the text from body, text, message, response, or output, in that order, and can set title and issue_id. Linear renders the text as Markdown.

output.json
{
  "title": "EUR totals are rounded twice at checkout",
  "body": "Orders in EUR are one cent off since 2.14.0. The total is rounded in the cart and again at payment."
}

Agent-tool and middleware payload

The model or middleware passes body, which is required and can't be empty, and optionally title and issue_id. Other fields are rejected.

connector-payload.json
{
  "body": "Reproduced: the total is rounded in the cart and again at payment.",
  "issue_id": "ENG-42"
}

Delivery and retries

When Linear rate-limits a comment or issue, connic waits and sends it again. The connector's runs show each delivery with the link to the comment or issue, or with the error.

Limits and errors

LimitValue
Answer to LinearLinear expects an answer within 5 seconds. connic answers right away and runs the agents afterwards.
Delivery ageconnic accepts a delivery only within one minute of when Linear sent it, as Linear recommends against replays.
Failed deliveriesLinear tries a delivery up to three more times, the last one 6 hours later, and may turn off a webhook that keeps failing.
API requests2,500 per hour for each Linear member, shared by all of the member's API keys. Each comment or issue takes one request. When Linear rate-limits, connic waits and retries the delivery.
Issue titleWithout a title, the first line of the text, cut at 255 characters.

Requests with a missing or wrong signature, or sent more than a minute earlier, get 401. Saving a Connection fails when Linear rejects the API key. Saving a connector fails when the team isn't in the key's workspace, and for inbound connectors when the key's member can't create webhooks. A delivery fails when Linear rejects it, for example when the issue doesn't exist.