Skip to content

Linear Plugin

Use the Linear plugin to find, create, update, comment on, and triage Linear issues from Slack. Each user connects their own Linear account through Linear’s hosted MCP server.

Optional webhooks let Junior publish issue.created events for subscriptions and event automations. User MCP OAuth and webhook ingress stay separate.

Terminal window
pnpm add @sentry/junior @sentry/junior-linear
plugins.ts
import { defineJuniorPlugins } from "@sentry/junior";
import { linearPlugin } from "@sentry/junior-linear";
export const plugins = defineJuniorPlugins([linearPlugin()]);

Register linearPlugin() so Junior loads the webhook route.

  • No LINEAR_API_KEY, shared workspace token, or custom OAuth app is required for the default setup.
  • An admin can also connect an optional read-only service account for people who have not connected Linear.
  • Each user completes Linear’s MCP OAuth flow the first time Junior calls a Linear MCP tool on their behalf.
  • Junior sends the authorization link privately, then resumes the same thread automatically after the user authorizes.
  • Webhooks use a separate Linear webhook secret. They do not use the user’s MCP OAuth grant.

Junior uses Linear’s hosted MCP tools for reads and writes. When an issue is created through that path, Junior links it to the current conversation.

A Junior admin can connect one Linear account that Junior itself uses, for example junior@example.com. Then people who have not connected Linear can find and read issues without OAuth. Scheduled automations can read Linear too.

  1. Create the Linear account and add it to your workspace. Give it only the teams that everyone who can talk to Junior may read.
  2. In the Junior dashboard, open Admin. Under Service accounts, click Connect on Linear. Only Junior admins see this section.
  3. Sign in to Linear as that account, not as yourself.
  4. Return to the Admin page. Linear shows as connected, with the admin who connected it.

If the dashboard is not available, run junior service-account connect linear on a machine with a browser and the deployment REDIS_URL.

The Linear plugin lists only Linear’s read tools for the service account, such as get_issue, list_issues, list_comments, list_projects, and list_teams. To create or update issues, comments, projects, or documents, Junior still asks the person to connect their own Linear account. After they connect, Junior uses their account for all Linear tools.

To remove the account, click Disconnect on the Admin page, or run junior service-account disconnect linear. If Linear revokes the grant, Junior removes the account and falls back to per-user OAuth.

To stop people from connecting their own Linear accounts, turn off user OAuth in your plugin list. Then everyone uses the shared account, and Junior never sends a Linear connect link. Junior hides the Linear tools that the service account does not list, so only reads stay available:

plugins.ts
export const plugins = defineJuniorPlugins([linearPlugin()], {
manifests: {
linear: { accounts: { userOAuth: false } },
},
});

Until an admin connects the account, Junior tells people that Linear is not available yet.

Linear can sync issues to GitHub repositories. When some of those repositories are public, tell action review which teams sync, so that it blocks private data in their issues:

plugins.ts
export const plugins = defineJuniorPlugins([
linearPlugin({
reviewContext:
"Issues in the Linear teams SDK and DOCS sync to public GitHub repositories. Other teams are internal.",
}),
]);

Action review reads this text in its system prompt. The agent does not see it. Without it, action review treats Linear as an internal destination.

Set conversation config with jr-rpc config set, or define the same keys for every conversation with createApp({ configDefaults }). Set deployment variables in the Junior environment, then redeploy. Explicit values in a request always win over conversation defaults.

linear.team

Default owning team for issue creation when a request does not name one.

  • Define: jr-rpc config set linear.team <team>
  • Install-wide default: configDefaults["linear.team"]
  • Required: No
  • Environment override: None
linear.project

Default project for issue creation when a request does not name one. Use it only when the conversation is genuinely centered on one project.

  • Define: jr-rpc config set linear.project <project>
  • Install-wide default: configDefaults["linear.project"]
  • Required: No
  • Environment override: None
LINEAR_WEBHOOK_SECRET

Webhook signing secret used to verify Linear issue webhooks.

  • Define: Set LINEAR_WEBHOOK_SECRET in the deployment environment
  • Required: Yes for events; otherwise no
  • Environment override: LINEAR_WEBHOOK_SECRET
  • Look up Linear issues, teams, projects, and related workflow state.
  • Create a new Linear issue from Slack thread context.
  • Update issue fields such as state, assignee, title, or description.
  • Add comments that preserve relevant code, Sentry, or reproduction links already present in the conversation.
  • Create temporary watches or durable event automations for new Linear issues when webhooks are enabled.

Create a Linear webhook in API settings for the workspace or team that should send issue events.

  1. Open Linear Settings → API → Webhooks.
  2. Create a webhook for the Issue resource.
  3. Set the webhook URL to:
https://<junior-host>/api/webhooks/linear
  1. Copy the webhook signing secret into LINEAR_WEBHOOK_SECRET.
  2. Redeploy Junior.

Junior verifies the Linear-Signature header on every delivery. Events stay disabled until LINEAR_WEBHOOK_SECRET is set.

Only workspace admins, or OAuth applications with the admin scope, can create or read Linear webhooks.

Set LINEAR_WEBHOOK_SECRET to enable watches. See Watches for the difference between temporary watches and durable event automations.

Subscribe to one issue with its Linear identifier, such as SRE-123.

issue.created

The issue was created.

Subscribe to all new issues in a team with the Linear team key, such as SRE.

issue.created

An issue was created in the team.

Create the watch or event automation before the issue arrives. Junior does not replay earlier webhooks.

Identifiers are normalized to uppercase. Prefer team-scoped event automations for monitor workflows that create many new issues.

An event automation selects a team or an issue with filters instead of an identifier. issue.created needs a team_key or an issue_identifier filter, because an issue carries its title and description and a team can be private. Junior saves both in uppercase. The filter does not check that the creator can see the team. See Automations.

Optional match values come from the resource type. For Linear issue and team events, team_key is the uppercase team key such as SRE. Junior drops events that do not match before it wakes the agent. For “all new issues in SRE”, a watch uses the team identifier and an event automation uses match.team_key.

OAuth: Ask Junior to create or update a real Linear issue, complete the private authorization flow, and confirm the issue key or URL returns in the same thread.

Webhooks: Create an event automation for a team key, then create a test issue in that team. You can also create an issue-scoped event automation with match.team_key set to the same team key and confirm non-matching teams do not fire.

  • Junior stores user MCP grants and does not include them in model input.
  • Webhooks use the Linear webhook signing secret, not user MCP OAuth.
  • Issue title, description, and other payload text are untrusted event content.
  • No auth prompt or no resume: Retry the Linear request and complete the private authorization flow when prompted.
  • Wrong team or project target: Include the team name, project name, or existing Linear issue key explicitly in the Slack request.
  • Duplicate or low-signal tickets: Give Junior the core problem, impact, and any supporting URLs from the thread so it can create a grounded issue instead of a vague summary.
  • Permission failures after connect: The user’s Linear account may not have access to that team, project, or issue. Retry with a resource the user can access.
  • Webhooks are ignored: Check LINEAR_WEBHOOK_SECRET, confirm the webhook points at /api/webhooks/linear, and confirm a matching watch or event automation exists.
  • Event automation stays unavailable: Events stay disabled until LINEAR_WEBHOOK_SECRET is set and Junior is redeployed.

Review Watches and Security Hardening.