Linear Adapter

Linear adapter with GraphQL API, HMAC-SHA256 webhook signature verification, issue comments, and reactions via the chat_sdk-linear gem.

The Linear adapter (chat_sdk-linear) integrates with the Linear GraphQL API for issue comments, reactions, and HMAC-SHA256 webhook signature verification.

Installation

# Gemfile
gem "chat_sdk"
gem "chat_sdk-linear"

Configuration

require "chat_sdk"
require "chat_sdk/linear"

linear = ChatSDK::Linear::Adapter.new(
  api_key: ENV["LINEAR_API_KEY"],             # Linear API key
  webhook_secret: ENV["LINEAR_WEBHOOK_SECRET"], # Webhook signing secret
  bot_username: ENV["LINEAR_BOT_USERNAME"]    # Bot display name (for filtering own messages)
)

api_key and webhook_secret are required. bot_username is recommended to filter out the bot's own comments from incoming events.

Environment Variables

Variable	Description
`LINEAR_API_KEY`	API key from Linear Settings > API
`LINEAR_WEBHOOK_SECRET`	Webhook signing secret from your Linear webhook configuration
`LINEAR_BOT_USERNAME`	The bot's display name in Linear (used to skip own messages in event parsing)

Linear Webhook Setup

Go to Settings > API > Webhooks in your Linear workspace.
Create a new webhook with the URL pointing to your server.
Select Comment events (create action).
Copy the webhook signing secret for LINEAR_WEBHOOK_SECRET.
Note the bot account's display name for LINEAR_BOT_USERNAME.

Webhook URL

https://your-domain.com/webhooks/linear

map "/webhooks/linear" do
  run bot.webhooks[:linear]
end

Capabilities

Capability	Supported	Notes
`reactions`	Yes	Emoji reactions on comments
`edit_messages`	No	Raises `NotSupportedError`
`delete_messages`	No	Raises `NotSupportedError`
`ephemeral_messages`	No	Raises `NotSupportedError`
`typing_indicator`	No	Raises `NotSupportedError`
`modals`	No	Raises `NotSupportedError`
`streaming_edit`	No	Raises `NotSupportedError`
`threads`	No	Raises `NotSupportedError`
`direct_messages`	No	Raises `NotSupportedError`
`message_history`	No	Raises `NotSupportedError`
`file_uploads`	No	Raises `NotSupportedError`

Events

The adapter parses webhook events for new comments:

Comment Create -- When a new comment is created on an issue, parsed as Events::Mention with thread_id: "linear:{issue_id}:c:{comment_id}".

Comments from the bot itself (matching bot_username) are automatically skipped.

Direct Client Access

linear_adapter = bot.adapter(:linear)
client = linear_adapter.client  # ChatSDK::Linear::ApiClient

# Create a comment on an issue
client.create_comment(issue_id: "issue-id", body: "Hello from ChatSDK!")

# Create a threaded reply
client.create_comment(issue_id: "issue-id", body: "Reply!", parent_id: "parent-comment-id")

# Add a reaction to a comment
client.create_reaction(comment_id: "comment-id", emoji: "thumbsup")

# Remove a reaction from a comment
client.delete_reaction(comment_id: "comment-id", emoji: "thumbsup")

Mention Formatting

Linear mentions use the @username format. Pass the username to mention:

linear_adapter.mention("quentin")  # => "@quentin"

Message IDs

Comments: Linear comment UUIDs (e.g., "a1b2c3d4-e5f6-...")
Thread IDs: Prefixed strings -- "linear:{issue_id}:c:{comment_id}"
Channel IDs: The Linear issue ID
Reply routing: When thread_id contains ":c:", post_message creates a threaded reply using the comment ID as parent_id

On this page