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.

The webhook URL carries a secret token for your account. Keep it private; if it leaks, press Regenerate, then Deploy again. Test Webhook checks delivery and Logs → opens the webhook log.

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 (see Workspaces). If the account has more than one tracker connected, pick Linear as the provider first.

Rule	Behavior
Shape	One Linear team per workspace, one workspace per team key in the account
Key	The team key (for example ENG): letters, digits, dash or underscore
Effect	A run started from an issue of that team runs in the workspace's repository, on the workspace's agents
Not linked	Tasks created in the workspace are internal, keyed with its task key prefix

When nothing is linked yet and the account has exactly one unlinked workspace, the first issue an automation pools from a team links that team to it. With two or more unlinked workspaces nothing is guessed; set the field by hand.

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. As it runs:

Moment	What happens in Linear
A step starts	The issue moves to the workflow state named by that step (for example In Progress), when status sync is on
A step finishes	The agent posts one comment with what it did, the evidence and a verdict
The run resolves	The issue moves to the team's completed state

A step's state is matched by name (case does not matter); the final move targets whichever state the team's workflow marks as completed. Status sync is best-effort: a state the team does not have is skipped and never fails the run. An is blocked by relation becomes a task dependency when the blocking issue is pooled too.

Kadmo never re-triggers itself: events caused by its own identity — its comments and status changes — are skipped, and an issue that already has an active run never starts a second one.

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.