Linear

A Linear trigger polls Linear’s GraphQL API (https://api.linear.app/graphql) for issues that match its filter and starts one run per new issue. It can also receive Linear webhooks for instant starts, and write back to the issue when runs start, succeed or fail.

For a complete walkthrough, see Linear issue to pull request.

Create an API key

Jimothy signs in to Linear with a personal API key.

1. In Linear, open Settings → Account → Security & access (the Create a personal API key link in Jimothy’s sign-in dialog opens https://linear.app/settings/account/security).
2. Under Personal API keys, create a new key and give it a label such as Jimothy.
3. If Linear asks for permissions, grant Read and Write. Read covers fetching issues, workflow states and your user; Write is needed for write-back comments and state changes. If Linear asks which teams the key can access, include every team your triggers watch.
4. Copy the key (it starts with lin_api_).

Then in Jimothy: Accounts → Linear, paste it into API key, and click Sign in.

Keys starting with lin_api_ are sent as the Authorization header as-is. Anything else is sent as Bearer <key>, so an OAuth access token also works.

Tip

Issues are read, commented on and moved as the key’s user. A dedicated Linear user for automation keeps that activity separate from yours, and makes Only issues assigned to me a clean hand-off: assign an issue to the bot to start a run.

Filter fields

Open Triggers → Add trigger → Linear. New Linear triggers start with labels jimothy, no team and no states.

Field	Stored as	Matching
Name	name	Display name.
Runs pipeline	pipelineId	The pipeline to start for each matching issue.
Linear account	connectionId	The signed-in account to read and write as. Required.
Team key	linear.teamKey	Optional. The team’s key, e.g. ENG (the prefix in issue ids like ENG-123). Exact match.
Labels (any of)	linear.labels	Comma separated. The issue must have at least one of these labels. Empty = any labels.
States	linear.states	Comma separated workflow state names, e.g. Todo, Ready for AI. Empty = any open state (every state whose type isn’t completed or canceled).
Project name	linear.projectName	Optional. Exact project name.
Only issues assigned to me (the account’s user)	linear.assignedToMe	Only issues assigned to the account’s user.
Poll every (seconds)	pollIntervalSeconds	Default 120, minimum 15. See Polling & dedup.
Run again when a processed issue is updated	retriggerOnUpdate	See Polling & dedup.
Webhook secret	webhook.secret	Linear signing secret for instant webhooks (below).
Write back to the issue	onStart, onSuccess, onFailure	Comment and/or move to a workflow state. See Write-back.

All filters are combined with AND. Each poll asks for the 50 most recently updated matching issues. The query Jimothy sends is equivalent to:

issues(filter: {
  team:     { key: { eq: "ENG" } },                      # Team key
  labels:   { some: { name: { in: ["jimothy"] } } },     # Labels (any of)
  state:    { type: { nin: ["completed", "canceled"] } },# or { name: { in: [...] } } with States
  assignee: { isMe: { eq: true } },                      # Only issues assigned to me
  project:  { name: { eq: "Q3 launch" } }                # Project name
}, first: 50, orderBy: updatedAt)

Click Preview matching issues in the trigger editor to run the query with your current settings (before saving). It lists up to eight matches with their key, title, state and labels, and the total count, or the error Linear returned.

What the run sees

Template value	From Linear
{{issue.key}}	identifier, e.g. ENG-123
{{issue.title}}	title
{{issue.description}}	description (Markdown)
{{issue.url}}	issue URL
{{issue.labels}}	label names, comma separated
{{issue.status}}	workflow state name
{{issue.priority}}	priority label, e.g. High
{{issue.assignee}} / {{issue.reporter}}	assignee name / creator name
{{issue.raw.teamId}} / {{issue.raw.teamKey}}	team id and key

See Template variables.

Instant starts with webhooks

Polling is always on. To start runs within seconds instead of waiting for the next poll, also send Linear’s webhooks to Jimothy:

1. Enable Settings → Webhook server and expose it with a tunnel. See Webhooks.
2. Save the trigger, then copy its URL from Instant webhook in the trigger editor (http://127.0.0.1:7717/hooks/<trigger-id>), and replace the host with your tunnel’s public URL.
3. In Linear: Settings → API → Webhooks → New webhook. Paste the URL, choose the team(s), and enable Issues events.
4. Copy the webhook’s signing secret from Linear into the trigger’s Webhook secret and save.

Jimothy verifies the Linear-Signature header (HMAC-SHA256 of the raw body) with that secret and rejects mismatches with HTTP 401. It accepts Issue events except remove, and applies the trigger’s filters to the webhook data:

• Team key, Labels (any of) and States are checked.
• Project name and Only issues assigned to me are not checked for webhook events.
• With States empty, webhook events are accepted in any state, including completed ones.

Webhook-started issues go through the same dedup as polled ones, so an issue that arrives by webhook and then by poll only runs once.

Write-back

On Linear, Comment posts a comment (Markdown) as the account’s user, and the transition field moves the issue to the named workflow state (case-insensitive, looked up within the issue’s team). For example: start → In Progress, succeed → In Review, fail → Todo. A state name that doesn’t exist fails with Linear workflow state "…" not found. See Write-back.

Keep issues from matching again

With the default “any open state” filter, an issue you’ve moved to In Review still matches. Dedup stops it from running twice, but a cleaner setup is to list explicit States (e.g. Ready for AI) and have the start write-back move the issue out of them (e.g. to In Progress).