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
An existing issue that your team links to a conversation (see below) is tracked, but the agent answers there only when someone @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:
  1. Click Link existing (or Link existing issue when nothing is linked yet).
  2. 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.
  3. Pick the issue. It appears in the panel with its live status.
Each linked issue shows how many conversations it rolls up. Expand N linked conversations to see each customer, their status and what they asked; click one to open it. Hover an issue and click × to unlink it from this conversation (the toast has Undo). Unlinking never changes the issue in Linear or its other conversations. When a linked issue is completed in Linear, Halo’s resolution follow-up (on by default; it waits a short grace period, 10 minutes unless changed, and skips any conversation where a teammate already replied) tells every linked conversation’s customer that the issue is fixed, exactly as it does for issues the AI filed. An unlinked conversation is no longer messaged. Linking needs Inbox: reply permission and a plan that includes Linear. The same actions are available to:
  • MCP clients: linear_link_issue and linear_unlink_issue (inbox:write scope), with ticket_id and issue (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_issues from a script to list which conversations an issue covers.

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.