Linear

Connect your Linear workspace so issues can start agent work and receive its progress. This page covers connecting Linear, linking a Linear team to a workspace, and what agents do on an issue. The rules that decide which issues start work — team, label, assignee, status and event filters — are set up under Automations.

Two ways to connect

Open Integrations → Issue Tracking → Linear. Depending on what the card offers, connect with the Linear app or with a personal API key.

	Linear app (OAuth)	Personal API key
Button	Connect with Linear	The key form (under Advanced · self-managed key when the app is offered)
Identity in Linear	A Kadmo app user in your workspace — not a billable seat	The Linear user who owns the key
Who approves	A Linear workspace admin approves the app; a Kadmo Admin starts the connection	A Kadmo Admin saves the key
Credential	Access token renewed automatically	The key, rotated by you
Inbound events	Delivered through the Kadmo app's shared webhook — nothing to deploy	A per-account webhook you register with Deploy
Agents	Receive a current Linear access token automatically	Need their own LINEAR_API_KEY in their environment

Connect with the Linear app

1. In the Linear dialog, press Connect with Linear.
2. Approve the app in Linear. If your workspace queues third-party app approvals, the request waits until a workspace admin clears it.
3. You land back on Integrations with Connected to Linear. The dialog shows the Workspace, the Identity (Kadmo app user), Token health, the access token's state (Auto-renewing) and the granted scopes.

The app asks for these scopes:

Scope	Why
read, write	Read issues, teams and workflow states; update issues
issues:create, comments:create	Create issues and post step comments
app:assignable, app:mentionable	Let people assign and mention the Kadmo app user
initiative:read, initiative:write	Read and write initiatives, which Goals use

If token refresh starts failing, the dialog says Token refresh is failing — Linear access is degraded — press Reconnect. If the app was removed (disconnected here or uninstalled in Linear), the dialog offers Reconnect with Linear.

Already on a personal key? The dialog offers Upgrade to the Linear app. Connecting replaces the stored key on this connection.

Connect with a personal API key

1. Create a personal API key at linear.app/settings/api. No workspace URL is needed — the key identifies your workspace.
2. Paste it into API Key and optionally set a Default team (for example ENG).
3. Press Test Connection — it answers Connected as … — then Save.
4. In the Webhook block, press Deploy to register the webhook with Linear for Issue and Comment events.

Keep the webhook URL private: see Per-account webhooks.

With a personal key, Kadmo does not hand a Linear credential to your agents. If agents should read and write Linear themselves, add LINEAR_API_KEY to each agent's environment (see Agents).

Link a Linear team to a workspace

A workspace declares the Linear team it serves, so an issue routes to the right repository and agents. Open the workspace's edit page and set the Linear team field on the Work intake card, using the team key (for example ENG). If the account has more than one tracker connected, pick Linear as the provider first. The rules of a link, and when one is made for you, are under Tracker routing.

What agents do on an issue

Linear has no issue types, so Kadmo uses the issue's first label in their place: the label is what automation filters and playbook routing match (a Bug label routes to Bug Fix by default). Change the routing on the Issue type routing page (see Playbooks).

A matching automation with a playbook action pools the issue in Tasks — auto-approved or held for review — and the run starts once its in-pool blockers are done. How the run reports on the issue is on What a run writes on the ticket. Kadmo's own notices can be a comment or nothing on Linear, and today Kadmo posts none on a Linear issue: see What applies today. On Linear:

• A step's workflow state (for example In Progress) is matched by name (case does not matter). Status sync is best-effort: a state the team does not have is skipped and never fails the run.
• The run resolves into whichever state the team's workflow marks as completed.
• An is blocked by relation is the issue's blocker in the pool.
• Events caused by Kadmo's own identity, its comments and status changes, are skipped; the other skip reasons are under What happens when an event arrives.

Disconnect

Disconnect in the dialog footer removes the connection.

• Linear app: Kadmo loses access to the workspace until you reconnect. The default team, automations and issue history stay.
• Personal key: inbound events stop and Kadmo loses access. The key is removed from Kadmo only — revoke it in Linear too.

Troubleshooting

Symptom	Cause and fix
Connection not completed — The connection was declined…	A Linear workspace admin has to approve the Kadmo app. Ask them to clear the pending request, then connect again.
Token refresh is failing	Press Reconnect in the Linear dialog.
Linear credentials not configured — save your Linear API key first on Deploy	Save the key before deploying the webhook.
The Linear app delivers its own events — no per-account webhook is needed	You are on the app path; there is nothing to deploy.
Nothing fires	Check the card is connected (and, on a personal key, that the webhook is deployed), then the rule's filters under Automations.
Runs land in the wrong repository	Link the team to the intended workspace on its Work intake card.
Agents cannot reach Linear on a personal key	Add LINEAR_API_KEY to the agents' environment.