Linear Bot

The Linear interaction is provided via the @useatlas/chat Chat SDK bridge plugin. Users can @mention the bot in Linear issue comments to query data. The bot replies with a Markdown comment containing the answer, SQL in code fences, and data as a table.

The Chat SDK adapter supports three authentication modes: personal API key, OAuth access token, and OAuth App client credentials. Webhook payloads are verified via HMAC-SHA256 when a webhook secret is configured.

Prerequisites

• A Linear workspace with API access enabled
• A publicly accessible HTTPS URL for webhook delivery
• One of: a personal API key, an OAuth access token, or an OAuth App (client credentials)

API Key Setup

The simplest approach — suitable for personal bots or testing.

1. Go to Linear Settings > Security & Access > Personal API keys
2. Create a new API key with appropriate scope
3. Save the key securely as LINEAR_API_KEY

OAuth App Setup (Recommended)

OAuth App auth uses client credentials for automatic token management. Recommended for production.

1. Create an OAuth Application

1. Go to Linear Settings > API > OAuth applications > Create application
2. Fill in the application name, description, and redirect URI
3. Note the Client ID and Client Secret

2. Configure Scopes

The application needs the following scopes:

• Read access to issues and comments
• Write access to comments (for posting replies)

Webhook Setup

1. Go to Linear Settings > API > Webhooks > Create webhook
2. Set the URL to your Atlas API endpoint:

   https://your-atlas-api.example.com/api/plugins/chat-interaction/webhooks/linear

3. Set a Signing secret and save it securely as LINEAR_WEBHOOK_SECRET
4. Under Resource types, enable:
   • Comment — for issue comment events
5. Click Create webhook

Configuration

API Key Auth

import { defineConfig } from "@atlas/api/lib/config";
import { executeAgentQuery } from "@atlas/api/lib/agent-query";
import { chatPlugin } from "@useatlas/chat";

export default defineConfig({
  plugins: [
    chatPlugin({
      adapters: {
        linear: {
          apiKey: process.env.LINEAR_API_KEY!,
          webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
          userName: "atlas-bot",
        },
      },
      executeQuery: executeAgentQuery,
    }),
  ],
});

OAuth Access Token

chatPlugin({
  adapters: {
    linear: {
      accessToken: process.env.LINEAR_ACCESS_TOKEN!,
      webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
    },
  },
  executeQuery: executeAgentQuery,
})

OAuth App (Client Credentials)

chatPlugin({
  adapters: {
    linear: {
      clientId: process.env.LINEAR_CLIENT_ID!,
      clientSecret: process.env.LINEAR_CLIENT_SECRET!,
      webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
    },
  },
  executeQuery: executeAgentQuery,
})

Options

Mounted Routes

The Chat SDK bridge mounts the following route for Linear:

How It Works

@Mentions in Issue Comments

1. A user @mentions the bot in a Linear issue comment
2. Linear sends a Comment webhook to the /webhooks/linear endpoint
3. The adapter subscribes the thread for follow-ups
4. The executeQuery callback runs the Atlas agent
5. Results are posted as a Markdown comment: answer text, SQL in code fences, data as a table

Threaded Follow-ups

1. After an initial response, the comment thread is subscribed via the Chat SDK state adapter
2. Follow-up replies in the same thread trigger new queries with conversation history
3. The agent has context from prior messages for multi-turn analysis

Comment Threading

Linear supports two levels of threading:

• Issue-level: Top-level comments on the issue
• Comment thread: Replies nested under a specific root comment

The adapter handles both — replies to the bot's comments are threaded under the original response.

Streaming

When executeQueryStream is configured, the adapter accumulates the full streamed response and posts it as a single comment once complete. Like GitHub, there are no progressive edits — the chunkIntervalMs setting has no effect on Linear.

Actions and Buttons

Linear does not support interactive buttons or card actions. Approval prompts (pending actions) are not rendered on this platform. If your workflow requires approval flows, use a platform that supports interactive cards (Slack, Teams, Discord).

Response Format

Responses are rendered as Markdown:

• Answer text as plain markdown
• SQL queries in ```sql code fences
• Data tables as Markdown tables
• Reactions supported (emoji reactions on comments)

Linear does not support rich cards or interactive buttons. The Chat SDK adapter automatically uses the markdown fallback format.

Environment Variables

Troubleshooting

Bot not responding to @mentions

1. Verify the webhook is configured and delivering successfully in Linear Settings > API > Webhooks
2. Check that the webhook URL is publicly accessible over HTTPS
3. Ensure the Comment resource type is enabled on the webhook
4. Check Atlas logs for initialization errors

Webhook signature verification failures

Ensure the webhookSecret in your Atlas config matches the signing secret configured in Linear webhook settings. The comparison is case-sensitive.

Bot replying to its own messages

The adapter uses the bot's user ID for self-message detection. For API key auth, set userName to match the account's Linear display name. For OAuth App auth, this is the application name.

Rate limiting

Linear's API has rate limits (documented in their API reference). The Chat SDK adapter handles rate limit responses and retries automatically. For high-traffic workspaces, OAuth App auth is recommended.

Reference

• Linear API documentation
• Linear webhooks documentation
• Linear OAuth documentation
• Chat SDK Bridge plugin
• Chat SDK documentation