Linear

What your agents can doCopy Anchor Link

Linear exposes a GraphQL API. Helios agents run GraphQL queries and mutations with your API key or OAuth token attached to API calls. Your connection's permissions determine which data and operations they can access.

• Create issues from a bug report, an alert, or a Slack thread, with labels, priority, and assignee
• Search the backlog and summarize a cycle or project
• Move issues between states, and change priority or assignee
• Comment on issues, project updates, and documents, and reply to comments
• Post project updates and read initiatives and customer requests

Agents can download files stored in Linear, such as images and files linked from issues, from uploads.linear.app. To add an image, an agent puts its URL in the markdown of an issue, comment or document, and Linear copies it into its own storage.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

Linear API KeyCopy Anchor Link

You need a Linear account that can create personal API keys. Admins can always create them, and members can if the workspace allows it. Triggers also need the key to belong to a workspace admin.

1. In Linear, open Settings → Account → Security & Access.
2. Under Personal API keys, create a key. Give it full access, or at least the Read, Write, and Admin permissions.
3. In Helios, choose Linear API Key and paste the key into Linear API Key.
4. Optional: to watch one team for triggers, enter its key, such as ENG, in Team.
5. Save.

Linear only lets admins create webhooks, so triggers need the Admin permission. A key without it can still make API calls within its permissions.

Your own Linear OAuth appCopy Anchor Link

You need to be a workspace admin to create OAuth applications in Linear.

1. In Linear, open Settings → Administration → API and create a new OAuth application.

2. Add this callback URL to the application:

   Copy Text

   https://api.heliosapp.com/integrations/linear/oauth_callback

3. In Helios, choose Your own Linear OAuth app and enter the application's Client ID and Client Secret. To use triggers, turn on Admin access. Optional: enter a team key in Team.

4. Save, then approve access in Linear. With Admin access, a workspace admin must approve it.

Helios asks for these scopes:

Linear only lets admins and apps with the admin scope create webhooks. Without Admin access, Helios doesn't ask for admin, registers no webhook, and shows every event as unavailable. Agents can still make API calls. Linear's app scopes, such as app:assignable and app:mentionable, are for apps installed as their own user. Helios connects as the member who approves the app, so it doesn't ask for them.

Linear records changes as the member who approved the app. Helios uses the refresh token Linear issues to renew expired access tokens. Deleting the connection revokes both tokens in Linear.

If you rotate the client secret in Linear, enter the new one in Helios through Manage and connect again. Connect again after you change Admin access too. If you turn off Admin access, Helios rejects deliveries from the webhooks it registered before but can't remove them. Delete the Helios webhooks in Linear under Settings → Administration → API.

TriggersCopy Anchor Link

Linear can start a Workflow when something happens in your workspace. Helios registers webhooks named Helios in Linear when you save the connection, so there is nothing to set up in Linear. This needs the Admin permission on the API key, or Admin access on an OAuth app connection. Saving the connection again updates its webhooks instead of adding more. Deleting the connection removes them.

Helios registers one webhook for all public teams, and one for each private team that the connecting member belongs to. Each webhook subscribes to every event below. Save the connection again to cover a private team that the member joins later. To watch one team only, set Team to the team's key, such as ENG.

• Team lists the teams the connection watches. That is the team set in Team on the connection. When Team is empty, it is every public team and the connecting member's private teams. It matches when the event belongs to one of the chosen teams. Comments, reactions, customer requests, and Issue SLA events belong to their issue's team, and a project matches if any of its teams is chosen. Events without a team, such as a comment on a document, a reaction to a comment, or a workspace label, don't match when Team is set.
• Label is a pattern. It matches when any label on the issue matches, such as bug or customer-*. Case matters.
• Moved to state is a pattern. It matches only updates that changed the issue's state, when the new state's name matches, such as In Progress or Done. Case matters.

All filters are optional.

Issue SLA events need a Linear plan with SLAs, and release and release note events need a plan with Releases. Linear refuses webhooks for a type that your plan doesn't include. Helios then subscribes to every other type and marks the refused type's events as unavailable in the trigger picker, with Linear's reason, such as "Release events need Linear's Business plan."

Deliveries are verified with the HMAC-SHA256 Linear-Signature header, and deliveries more than a minute old are rejected. Save the connection again in Helios to re-enable its webhook if Linear disables it after failed deliveries.

Not coveredCopy Anchor Link

Helios doesn't subscribe to these Linear webhook types:

Agents can't use Linear's GraphQL subscriptions. Subscriptions need a WebSocket connection, and agents call the API over HTTP.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Linear rejected the key or token.
• The webhook: in Linear, open Settings → Administration → API. A webhook named Helios should be listed, plus one for each private team that Helios watches.
• A trigger:
  1. Add issue.created to a workflow with no filters.
  2. Create a test issue in Linear.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.

Common errorsCopy Anchor Link