Skip to main content

​
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, write
  • issues:create
  • comments:create
  • app:mentionable
  • app:assignable
After approval, the Halo Linear app appears in your Linear workspace and can be assigned to issues, mentioned in comments, and used to create new tickets.

​
Webhook

Linear webhooks are configured at the Linear app level (one webhook per Halo deployment, not per customer). The endpoint:
Verification uses HMAC-SHA256 with 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 create events from human users on tracked issues.
  • Issues: create + update only. remove is ignored to preserve the historical row in the inbox.
  • Issue attachments: create, update, remove all handled; rows are upserted/deleted in linear_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_attachments table is RLS-scoped to org members. End-user surfaces (the SDK chat widget) cannot read it.
  • The getLinearTicketInfo AI 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.
If you build a new surface that touches Linear data, treat attachments as engineer-only by default.

​
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_bug vs needs_review
  • Priority — 0–4 (Linear priority scale)
Classification logic: bugs the AI is highly confident about go in as 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, or integration_request
Use this to keep your Linear backlog populated with real customer demand without manually translating Halo conversations.

​
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

  1. Go to Integrations > Linear
  2. Click Create Linear Agent (or use the agent template at AI Agents > New)
  3. The agent is created with sensible defaults — instructions optimized for concise, technical replies aimed at developers, with knowledge search enabled
You can customize the agent like any other agent.

​
Response modes

The Linear Agent’s behavior on dev comments is controlled by response_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
It also has knowledge search enabled, so it can answer “is this expected behavior?” or “is there a setting that controls this?”

​
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

​
Read tool: getLinearTicketInfo

Beyond actions, agents can use a passive getLinearTicketInfo 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_enabled toggles
  • Default team and labels

​
Where to go next

Agent Actions

Enable Linear actions per agent.

Agent Channels

Configure which agents file Linear tickets.