Linear integration

What it does

The Linear integration lets your agency drive a client's Linear workspace from TaskJuice. Connect a workspace once and your workflows can create, update, search, archive and link issues; post and edit comments; open projects and publish project updates; attach links; record customer requests; and read the teams, members, workflow states, cycles and labels those choices are made from. Every field that picks something bounded — a team, a state, an assignee, a project, a label, a cycle, a customer — renders as a dropdown of live options, so nothing asks you to paste a UUID.

31 webhook triggers cover Linear's data-change events. TaskJuice registers and tears down the Linear webhook subscription for you when you publish and unpublish the workflow.

Connect a Linear account

Linear requires each agency to bring its own OAuth application (BYOC). Create one at linear.app/settings/api/applications/new, then add it in TaskJuice under Apps → Linear.

1. On the Linear application, add your TaskJuice callback URL under Redirect URIs. It must match the Redirect URI shown on the TaskJuice Linear client exactly.
2. Turn Public on if any client authorizes from a Linear workspace other than the one that owns the application. A private application can only be authorized by members of its own workspace.
3. Leave Client credentials and Webhooks off. TaskJuice uses the authorization-code flow and registers its own webhooks through the API, so Linear's per-application webhook would only deliver a second copy of every event.
4. In TaskJuice, paste the Client ID and Client secret into the Linear client, tick the scopes your workflows need (read, write, issues:create, comments:create and admin), save, and click Verify.
5. Add the connection from the Linear node in the workflow editor, sign in to the Linear workspace that should authorize it, and approve the consent screen.

The admin scope is not optional if you use triggers. Linear gates webhook creation on it — "Only workspace admins, or OAuth applications with the admin scope, can create or read webhooks" — so a client without it can run actions but cannot subscribe to events. TaskJuice refuses to publish a workflow whose Linear trigger is bound to a connection that never received the scope, rather than letting it go live with a subscription that was never registered.

Linear access tokens last 24 hours and refresh automatically. To revoke access, open Linear, go to Settings, API, and remove the authorization. The full grant flow is documented in the Linear OAuth 2.0 guide.

Triggers

Every trigger delivers Linear's data-change envelope: action (create, update or remove), type, createdAt, organizationId, the serialized entity under data, the actor who caused it, and — on updates — the previous values under updatedFrom.

Issues

• linear/issue-created — Triggers when a Linear issue is created. Delivered as Linear's Issue:create data-change webhook.
• linear/issue-updated — Triggers when a Linear issue is updated. Delivered as Linear's Issue:update data-change webhook.
• linear/issue-removed — Triggers when a Linear issue is deleted or trashed. Delivered as Linear's Issue:remove data-change webhook.

Comments and reactions

• linear/comment-created — Triggers when a Linear comment is created. Delivered as Linear's Comment:create data-change webhook.
• linear/comment-updated — Triggers when a Linear comment is updated. Delivered as Linear's Comment:update data-change webhook.
• linear/comment-removed — Triggers when a Linear comment is deleted. Delivered as Linear's Comment:remove data-change webhook.
• linear/reaction-added — Triggers when someone reacts to a Linear comment. Delivered as Linear's Reaction:create data-change webhook.
• linear/reaction-removed — Triggers when someone removes a reaction from a Linear comment. Delivered as Linear's Reaction:remove data-change webhook.

Projects and initiatives

• linear/project-created — Triggers when a Linear project is created. Delivered as Linear's Project:create data-change webhook.
• linear/project-updated — Triggers when a Linear project is updated. Delivered as Linear's Project:update data-change webhook.
• linear/project-removed — Triggers when a Linear project is deleted. Delivered as Linear's Project:remove data-change webhook.
• linear/project-update-created — Triggers when a status update is posted on a Linear project. Delivered as Linear's ProjectUpdate:create data-change webhook.
• linear/project-update-updated — Triggers when a project status update is edited. Delivered as Linear's ProjectUpdate:update data-change webhook.
• linear/initiative-created — Triggers when a Linear initiative is created. Delivered as Linear's Initiative:create data-change webhook.
• linear/initiative-updated — Triggers when a Linear initiative is updated. Delivered as Linear's Initiative:update data-change webhook.
• linear/initiative-update-created — Triggers when a status update is posted on a Linear initiative. Delivered as Linear's InitiativeUpdate:create data-change webhook.
• linear/initiative-update-updated — Triggers when an initiative status update is edited. Delivered as Linear's InitiativeUpdate:update data-change webhook.

Documents and attachments

• linear/document-created — Triggers when a Linear document is created. Delivered as Linear's Document:create data-change webhook.
• linear/document-updated — Triggers when a Linear document is updated. Delivered as Linear's Document:update data-change webhook.
• linear/attachment-created — Triggers when a link is attached to a Linear issue. Delivered as Linear's Attachment:create data-change webhook.
• linear/attachment-updated — Triggers when an issue attachment is edited. Delivered as Linear's Attachment:update data-change webhook.

Customers

• linear/customer-created — Triggers when a Linear customer is created. Delivered as Linear's Customer:create data-change webhook.
• linear/customer-updated — Triggers when a Linear customer is updated. Delivered as Linear's Customer:update data-change webhook.
• linear/customer-need-created — Triggers when a customer request is recorded in Linear. Delivered as Linear's CustomerNeed:create data-change webhook.
• linear/customer-need-updated — Triggers when a recorded customer request changes. Delivered as Linear's CustomerNeed:update data-change webhook.

Workspace

• linear/cycle-created — Triggers when a Linear cycle (sprint) is created. Delivered as Linear's Cycle:create data-change webhook.
• linear/cycle-updated — Triggers when a Linear cycle's dates, name or scope change. Delivered as Linear's Cycle:update data-change webhook.
• linear/issue-label-created — Triggers when a label is created in the Linear workspace. Delivered as Linear's IssueLabel:create data-change webhook.
• linear/issue-label-updated — Triggers when a Linear label is renamed or recolored. Delivered as Linear's IssueLabel:update data-change webhook.
• linear/user-created — Triggers when a member joins the Linear workspace. Delivered as Linear's User:create data-change webhook.
• linear/user-updated — Triggers when a workspace member's profile, role or active state changes. Delivered as Linear's User:update data-change webhook.

Linear signs every delivery with an HMAC-SHA256 hex digest of the raw body on the Linear-Signature header. TaskJuice verifies that signature against the secret it supplied when registering the subscription, and rejects anything that fails before the workflow sees it.

Actions

Issues

• linear/create-issue — Creates an issue in a Linear team, with optional assignee, workflow state, project, cycle, labels and due date.
• linear/update-issue — Updates an existing Linear issue. Fields left blank are not sent, so they keep their current value.
• linear/get-issue — Reads a single Linear issue by UUID or identifier, including its state, assignee, team, project and labels.
• linear/list-issues — Lists issues, optionally narrowed by team, workflow state, assignee, project or label.
• linear/list-my-issues — Lists issues assigned to the connected Linear user.
• linear/search-issues — Full-text search across workspace issues by title, description and optionally comments.
• linear/archive-issue — Archives a Linear issue. Archived issues leave the active board but stay readable and can be unarchived.
• linear/unarchive-issue — Restores a previously archived Linear issue to the active board.
• linear/delete-issue — Deletes a Linear issue. Linear keeps it recoverable for 30 days unless Permanently Delete is on, which is admin-only.
• linear/create-issue-relation — Links two Linear issues as blocking, duplicate, related or similar.

Labels

• linear/add-issue-label — Adds an existing workspace label to a Linear issue.
• linear/remove-issue-label — Removes a label from a Linear issue.
• linear/create-label — Creates a workspace or team label that issues can then be tagged with.
• linear/list-labels — Lists the issue labels available in the Linear workspace.

Comments

• linear/create-comment — Posts a comment on a Linear issue, or replies to an existing comment thread.
• linear/update-comment — Edits the body of an existing Linear comment.
• linear/get-comment — Reads a single Linear comment by UUID, including its author and parent issue.
• linear/list-comments — Lists comments, optionally narrowed to a single issue.
• linear/delete-comment — Deletes a Linear comment.

Projects

• linear/create-project — Creates a Linear project owned by a team, with an optional lead, dates and description.
• linear/update-project — Updates a Linear project. Fields left blank are not sent, so they keep their current value.
• linear/get-project — Reads a single Linear project, including its lead, status, dates and owning teams.
• linear/list-projects — Lists the projects in the Linear workspace.
• linear/create-project-update — Posts a status update on a Linear project, optionally setting the project health.

Attachments and documents

• linear/create-attachment — Attaches a link to a Linear issue. Re-posting the same URL updates the existing attachment rather than duplicating it.
• linear/create-document — Creates a Linear document, optionally filed under a project.
• linear/get-document — Reads a single Linear document by UUID or slug, including its Markdown content.

Customers

• linear/create-customer — Creates a customer record in Linear's customer requests workspace.
• linear/update-customer — Updates a Linear customer. Fields left blank are not sent, so they keep their current value.
• linear/get-customer — Reads a single Linear customer, including its owner, status and tier.
• linear/list-customers — Lists the customer records in the Linear workspace.
• linear/create-customer-need — Records a customer request against a Linear issue or project. Linear requires either an issue or a project.
• linear/update-customer-need — Updates a recorded customer request — its body, priority, or the issue or project it points at.

Workspace

• linear/list-teams — Lists the teams in the Linear workspace.
• linear/get-team — Reads a single Linear team, including its key, issue count and cycle settings.
• linear/list-users — Lists the members of the Linear workspace — the assignees, leads and owners other actions select.
• linear/get-user — Reads a single Linear workspace member by UUID.
• linear/list-workflow-states — Lists the workflow states (Todo, In Progress, Done …) a team's issues can move through.
• linear/list-cycles — Lists a team's cycles (sprints), with their dates and completion progress.

Escape hatch

• linear/execute-graphql — Runs an arbitrary query or mutation against the Linear GraphQL API. It can run any mutation, so consider setting the step to Pause for approval.

Known limitations

• One endpoint, one budget. Every action posts a GraphQL document to https://api.linear.app/graphql, so reads and writes share the same rate-limit allowance per connection. Linear also prices each request by query complexity, so a wide list costs more than a narrow one.
• Failures arrive as HTTP 200. Linear reports permission, validation and not-found errors in an errors array inside a 200 response. TaskJuice treats any response carrying errors as a failed step and surfaces Linear's first message, so these behave like ordinary step failures in On Error and retries.
• Customers and customer requests need the feature enabled. The customer actions and the Customer / CustomerNeed triggers only work once Customers is turned on in the Linear workspace's settings. Until then Linear refuses the call with "Customers must be enabled in workspace settings to create customers", and TaskJuice shows that message on the failed step. The Free plan can turn it on.
• Workflow state and cycle lists follow the team. Pick the team first and the Workflow State and Cycle dropdowns list only that team's states and cycles. Where the team is optional and left empty, they list every team's, and a name such as "Todo" can appear once per team. Cycles Linear created on its schedule have no name, so they appear as "Cycle 3".
• Deleting an issue is reversible for 30 days. linear/delete-issue moves the issue to Linear's 30-day recovery window. Turn on Permanently Delete to skip it — that is admin-only and cannot be undone. Prefer linear/archive-issue for day-to-day cleanup.
• Pickers list the first 250 records. Team, state, assignee, project, label, cycle and customer dropdowns read one page. On a larger workspace, switch the field to expression mode with the {} toggle and supply the id from an upstream step.
• Free-plan caps. Linear's Free plan allows 2 teams and 250 active issues, which is the ceiling a trial connection will hit first.