What Linear adds to Halo
Linear is an actions-only integration:
There’s no ingest mode (Halo doesn’t pull existing Linear issues into knowledge) and no notifications mode (your team uses Linear’s native notifications).
Connect at Integrations > Linear.
Setup
Connecting
Click Connect Linear. You’ll be redirected to Linear’s OAuth consent screen as an app actor (actor=app). Required scopes (comma-separated):
read,writeissues:createcomments:createapp:mentionableapp:assignable
Webhook
Linear webhooks are configured at the Linear app level (one webhook per Halo deployment, not per customer). The endpoint:LINEAR_WEBHOOK_SECRET and a 60-second timestamp window.
Required resource subscriptions
Enable the following resource types on the Halo Linear app’s webhook in your Linear workspace settings:
Halo is intentionally narrow about what it processes:
- Comments: only
createevents from human users on tracked issues. - Issues:
create+updateonly.removeis ignored to preserve the historical row in the inbox. - Issue attachments:
create,update,removeall handled; rows are upserted/deleted inlinear_issue_attachments. - Everything else (Reactions, Projects, Cycles, etc.) returns 200 with no work.
Attachments are dashboard-only
Linear attachments often contain internal screenshots, signed S3 URLs, error reports, or other private artifacts. Halo enforces a strict boundary:- The
linear_issue_attachmentstable is RLS-scoped to org members. End-user surfaces (the SDK chat widget) cannot read it. - The
getLinearTicketInfoAI read tool intentionally does not include attachments in its return shape, so the AI cannot leak them into a customer reply. - The inbox right-rail Attachments section is labeled “internal, not shown to customers” so support agents understand the boundary.
Actions
create_bug
The agent files a bug ticket in Linear when it detects a confirmed bug in a conversation.
Configuration on the agent’s action card:
- Default team — which Linear team gets the ticket
- Labels — added to every filed bug
- Confidence threshold — only file when the agent is at least N% sure it’s a bug (vs user error)
- Classification —
confirmed_bugvsneeds_review - Priority — 0–4 (Linear priority scale)
confirmed_bug. Anything ambiguous goes in as needs_review for a human to triage.
create_feature_request
The agent captures customer feature requests, improvements, and integration asks as Linear tickets.
Configuration:
- Same team/labels as
create_bug - Classification —
feature_request,improvement, orintegration_request
The Linear Agent
When you set up Linear, you can also create a dedicated Linear Agent that replies to dev comments on Halo-created Linear tickets.How it works
1
Bug detected in conversation
During a customer chat, the AI identifies a bug and creates a Linear ticket using
create_bug with relevant details — error messages, steps to reproduce, browser info, user context.2
Developer comments on the ticket
An engineer picks up the ticket and leaves a comment — for example, “What page was the user on?” or “Can you share the full error message?”
3
Linear Agent replies with context
The Linear Agent reads the comment, searches the original conversation, and posts a reply directly on the Linear ticket.
Setup
- Go to Integrations > Linear
- Click Create Linear Agent (or use the agent template at AI Agents > New)
- The agent is created with sensible defaults — instructions optimized for concise, technical replies aimed at developers, with knowledge search enabled
Response modes
The Linear Agent’s behavior on dev comments is controlled byresponse_mode on the action config:
When using mention-only, include
@halo anywhere in the comment to trigger a response:
What the agent can answer
The Linear Agent has access to:- Error details — error messages, stack traces, codes
- Steps to reproduce — what the customer was doing
- User environment — browser, OS, device, custom traits
- User and company info — name, email, plan, custom fields
- Conversation history — the full back-and-forth
Limitations
The Linear Agent only replies to comments on tickets that Halo created. It does not respond to comments on:- Tickets created manually in Linear
- Tickets created by other tools
- Comments from other agents/bots
@halo mentions it, whatever its response mode.
Linking conversations to existing issues
One Linear issue often covers many customer conversations. In the inbox, the conversation’s Linear panel lets you link the conversation to an issue that already exists, instead of filing a new one:- Click Link existing (or Link existing issue when nothing is linked yet).
- Search by identifier (
ENG-123), paste the issue’s linear.app link, or type words from its title. Only issues in your connected Linear workspace show up. - Pick the issue. It appears in the panel with its live status.
- MCP clients:
linear_link_issueandlinear_unlink_issue(inbox:writescope), withticket_idandissue(ENG-123, a link, or the issue id). - Ask AI: the same two tools, for team members with Inbox reply access when Linear is connected. Ask AI can also query
ticket_linear_issuesfrom a script to list which conversations an issue covers.
Read tool: getLinearTicketInfo
Beyond actions, agents can use a passivegetLinearTicketInfo read tool when org-level read_enabled is on. This lets the agent pull ticket details when a customer references a specific ticket ID in a conversation.
Toggle read_enabled on the integration page.
Status and stats
The integration page shows:- Total Linear issues tracked by Halo
- Confirmed bugs vs needs review breakdown
- Feature requests count
read_enabled,reply_enabled,customer_messaging_enabledtoggles- Default team and labels
Where to go next
Agent Actions
Enable Linear actions per agent.
Agent Channels
Configure which agents file Linear tickets.