Linear
Linear is supported as a hosted connector: real webhook, real Discover scan, /align capture in
comments. It is not at the same maturity as Slack, Teams, Jira or GitHub, and this page says
exactly where the line is.
connectors.linear.enabled is false in the chart's default values, so a stock install does not
run it. On Align Cloud, ask us to enable it. Self-hosting, set the flag - see
Configuration.
No ambient capture. Slack, Teams, Jira, GitHub and Confluence can notice a decision-shaped
conversation and offer to capture it; Linear cannot. Every Linear capture is an explicit
/align comment.
If ambient capture on Linear matters to you, tell us - it is a known gap, not a design choice.
What it does
- Capture -
/alignin a Linear issue comment - Discover - scan Linear issue and project history for past decisions
- Evidence linking - a decision keeps a link back to the issue that produced it
- CLI import -
align import linearbuilds a personal graph with no account and no connector
Setup
- Settings → Integrations → Connect next to Linear
- Authorise Align in Linear
- Choose which teams are in scope
Capturing a decision
In a comment on any Linear issue:
/align We're moving the notification service off polling and onto webhooks
Align reads the issue and the comment thread for context, creates a Decision Snapshot, and links it back to the issue.
Webhook security
The Linear webhook verifies every delivery with an HMAC signature and rejects the request when no secret is configured. That is deliberate: an unset secret is a misconfiguration, not a reason to accept unsigned traffic. Deliveries are also de-duplicated so a Linear retry cannot create the same decision twice.
OAuth scope
Connecting Linear asks for read only. issues:create is requested later, when you switch on
the ticket feature (linear_ticket_proxy), and comments:create when you switch on the comment
feature (linear_comments). The consent screen names each one. The lists are read
from services/gateway/src/auth/connectorScopeSets.ts.
| Scope | When | Why |
|---|---|---|
read | The first connect | Read issues, comments, projects and teams for context and for Discover |
issues:create | When the ticket feature is switched on | Create a new issue when a person asks Align to, for example @Align create ticket in Slack |
comments:create | When the comment feature is switched on | Post a comment on a Linear issue, for example the notice when a new decision conflicts with one captured there |
With a read-only grant, creating a ticket answers 403 write_scope_missing, names the feature and
the issues:create scope, and nothing is created. A re-consent keeps what the grant already holds.
With a grant that lacks comments:create, Align's own comment paths post nothing and send nothing to Linear. As with tickets, a member who can use the connection can obtain its token and call Linear directly, so the scope on Linear's side is the real limit. The
conflict notice is skipped and logged, and the post_comment tool answers that the comment
permission is not granted. A connection made before this feature keeps working for everything it
could already do, and shows the comment feature as off until an admin switches it on. A grant that
holds Linear's broader write scope counts as having it.
Linear describes issues:create as "Allows creating new issues and their attachments". Align does not ask for Linear's broader write scope. Align creates an issue when a person asks it to, or when an agent or connector tool does, using the connection's token. @Align create ticket and the Linear connector's linear.create_issue tool both run Align's alignment check before they create anything. A member who can use the connection can also obtain its token and call Linear directly. That call does not pass through Align's check, and the issue it makes shows as created by Align. The scope covers new issues and their attachments.
Align connects to Linear as an app, so an issue it creates shows as created by Align, not as the admin who connected Linear. @Align create ticket in Slack also passes the name of the person who asked, so Linear shows "Sofie (via Align)". Issues made another way show plain "Align": the Slack decision-card button, Teams, the linear.create_issue tool, the CLI and agents. Linear may ask a workspace admin to approve an app install.
A Linear connection made before this change keeps its old behaviour until you disconnect and reconnect Linear: a read-only grant cannot create issues, and a grant made before Align connected as an app shows the admin's name and no requester name. Until you reconnect or switch the ticket feature on, @Align create ticket on a read-only grant answers that it could not create the ticket, and nothing is created.
Evidence captured
- Issue link and identifier (for example
ENG-123) - Issue title and status
- Project name
- Team name
Using the CLI instead
You do not need the hosted connector to get Linear history into a graph:
align import linear --token <linear-api-key>
This builds a personal graph on your machine - no shared org graph, no real-time capture, no cross-team conflict detection. See the CLI guide.