Mattering Automations Linear integration
Connect Linear to Mattering Automations: issues, comments, projects, milestones, cycles, labels, workflow states, teams, and users as workflow steps, authenticated with a Linear personal API key.
The Mattering Automations Linear integration adds Linear to your automation canvas: create, update, search, archive, and delete issues, add and remove labels, post and edit comments, create and update projects, read project milestones and cycles, and resolve the teams, users, and workflow states the rest of the calls depend on.
Linear's public API is a single GraphQL endpoint rather than a REST API, so each node in this integration is a named GraphQL operation with a fixed document behind it. You fill in ordinary canvas fields and the node builds the variables, so nothing here asks you to write GraphQL unless you choose the advanced custom request node.
Setup takes a few minutes: create a personal API key in Linear, attach it as a credential in Mattering, and run one read-only node to confirm it works. One detail is worth reading before you start, because it is where most Linear setups go wrong: the key is sent raw in the Authorization header, with no Bearer prefix. This guide walks through each step and ends with the full node reference.
Before you start
- A Linear account with access to the teams, issues, and projects you want to automate.
- A Mattering workspace with access to the Automations app.
- Permission to create a personal API key in your Linear workspace settings.
- An awareness that a Linear personal API key is user-scoped and carries that user's full permissions across every team they can see. There is no read-only or per-team personal key, so treat a stored Linear credential as equivalent to that person's account and create it from an account whose access matches what automations should reach.
Create a Linear personal API key
Mattering authenticates to Linear with a personal API key, sent as a raw Authorization header. You create it in your Linear workspace settings, not from an app or an integration listing.
Connect Linear to Mattering
Verify it works
Open any automation canvas and check the palette: a Linear section should list the read and action nodes. Drop Linear: Get Current User onto the canvas and run a test step. It takes no parameters and is a safe, read-only query, so a successful response returns the name, email, and id of the account the key belongs to. This is the real connectivity probe for this connector.
Check the account it names. Because the key is user-scoped, the account in that response is exactly what your automations will act as, and its workspace is the only workspace they can reach.
To confirm the key can see your work, add Linear: List Teams and run it. A successful response lists the teams in the workspace with their keys. Copy a team id from the result and feed it to Linear: Get Team, which returns that team's workflow states, members, and active cycle in one call. Those are the state id and assignee id most other nodes need.
Node reference
35 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 18
Linear: Get Current User
linear_get_viewer
Get the Linear account the API key belongs to. Takes no parameters, so it is the cheapest auth and connectivity probe.
Linear: Get Issue
linear_get_issue
Get one issue with its full record: description, state, assignee, team, project, cycle, parent, and labels.
Linear: Get Organization
linear_get_organization
Get the Linear workspace (organization) the API key belongs to, including its URL key and seat count.
Linear: Get Project
linear_get_project
Get one project with its full body content, its teams, and its members.
Linear: Get Team
linear_get_team
Get one team with its workflow states, its members, and its active cycle. The fastest way to resolve the state id and assignee id you need to file an issue.
Linear: Get User
linear_get_user
Get one Linear user by id.
Linear: Get Workflow State
linear_get_workflow_state
Get one workflow state by id, including which team it belongs to.
Linear: List Cycles
linear_list_cycles
List cycles (sprints) with their dates and progress. Filter by team, then use the cycle id when creating or moving issues.
Linear: List Issue Comments
linear_list_issue_comments
List the comments on an issue, including who wrote each one and whether it has been resolved.
Linear: List Issue Labels
linear_list_issue_labels
List issue labels. Workspace labels have a null team; team labels carry their team. Use it to resolve label ids for issue creation.
Linear: List Issues
linear_list_issues
List issues across the workspace with a structured filter, e.g. every started issue on one team. Descriptions and labels are left out to keep the query cheap; use Linear: Get Issue for the full record.
Linear: List Project Issues
linear_list_project_issues
List the issues attached to a project, optionally narrowed with an issue filter.
Linear: List Project Milestones
linear_list_project_milestones
List project milestones, optionally filtered to one project. Use it to resolve the milestone id an issue should be filed against.
Linear: List Projects
linear_list_projects
List projects in the workspace with their status, lead, dates, and progress.
Linear: List Teams
linear_list_teams
List the teams in the workspace with their keys. Every issue belongs to a team, so this is usually the first call in a Linear automation.
Linear: List Users
linear_list_users
List the members of the Linear workspace. Use it to resolve a user id for an assignee before creating or updating an issue.
Linear: List Workflow States
linear_list_workflow_states
List workflow states (Backlog, Todo, In Progress, Done, Canceled) across the workspace. Filter by team to get the state ids that Linear: Update Issue needs.
Linear: Search Issues
linear_search_issues
Full text search across issues. Use this when you have words rather than ids; use Linear: List Issues when you have a structured filter.
Action nodes 17
Linear: Add Label to Issue
linear_add_issue_label
Add one label to an issue without touching its other labels.
Linear: Archive Issue
linear_archive_issue
Archive an issue, optionally moving it to the trash. Reversible with Linear: Unarchive Issue.
Linear: Create Comment
linear_create_comment
Post a comment on an issue, a project, or a project update. Supply exactly one target id.
Linear: Create Issue
linear_create_issue
Create a Linear issue. Only the team id and a title are required; everything else is optional.
Linear: Create Issue Label
linear_create_issue_label
Create an issue label. Supply a team id for a team label, or leave it blank for a workspace label.
Linear: Create Project
linear_create_project
Create a project. Linear requires a name and at least one owning team.
Linear: Custom GraphQL Request
linear_graphql_request
Advanced: run any Linear GraphQL operation with your own document and variables. Covers everything not individually typed, including initiatives, documents, attachments, customers, and admin mutations.
Linear: Delete Comment
linear_delete_comment
Delete a comment. Destructive and not recoverable through the API.
Linear: Delete Issue
linear_delete_issue
Delete an issue. By default it goes to the trash; set permanently_delete to remove it outright. Destructive.
Linear: Delete Issue Label
linear_delete_issue_label
Delete an issue label and remove it from every issue that carries it. Destructive.
Linear: Delete Project
linear_delete_project
Delete a project. Its issues stay in their teams but lose the project link. Destructive.
Linear: Remove Label from Issue
linear_remove_issue_label
Remove one label from an issue. The label itself is not deleted.
Linear: Unarchive Issue
linear_unarchive_issue
Restore an archived issue back into its team's active issue list.
Linear: Update Comment
linear_update_comment
Edit a comment's body, or mark it resolved by naming the resolving user.
Linear: Update Issue
linear_update_issue
Update an issue: move it to another state, reassign it, reprioritise it, retitle it, or move it between teams and projects. Only the fields you fill in are sent.
Linear: Update Issue Label
linear_update_issue_label
Rename an issue label or change its colour, description, or parent group.
Linear: Update Project
linear_update_project
Update a project: rename it, move its status, change its lead, or shift its dates. Only the fields you fill in are sent.
Using the integration
On the automation canvas
Linear nodes chain with every other node: an inbound report can become a filed issue, an AI step can draft the title and judge the severity in between, and the resulting issue identifier can open a task in Mattering Productivity. Linear: Delete Issue, Linear: Delete Project, Linear: Delete Comment, and Linear: Delete Issue Label are destructive, so put a condition or an approval step in front of them.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can file issues, move them between states, search the backlog, and comment through the same nodes your workflows use.
Resolving Linear ids before you write anything
Almost every write needs an id rather than a name. Linear: List Teams gives you team ids, Linear: List Workflow States gives you the state ids that Linear: Update Issue needs, Linear: List Users gives you assignee ids, and Linear: List Issue Labels gives you label ids. Linear: Get Team is the shortcut: it returns a team's workflow states, members, and active cycle together, which is usually everything one issue-filing workflow needs.
Issue ids and identifiers like ENG-123
The UUID is the safe form and is what every id argument accepts. Linear's own mutation examples also pass the human identifier, such as ENG-123, and it appears to be accepted wherever a UUID is, but that is not confirmed for every argument, so a workflow that has both should pass the UUID. Linear: Search Issues and Linear: List Issues both return the UUID alongside the identifier, so it is easy to carry the right one forward.
Filtering and paging list nodes
Every list node takes the same five arguments: a page size, a cursor from the previous page, a filter object, an include-archived toggle, and a sort field of createdAt or updatedAt. Filters use Linear's own comparator grammar, so an issue filter can read as state, then type, then eq, then started, and relationships nest the same way. The filter type is named on each node's help text with a worked example.
Beyond the typed nodes
Each typed node also accepts an extra variables object that is merged into the GraphQL variables before sending, so input-object fields the node does not expose individually are still reachable. For anything the typed set does not cover at all, including initiatives, documents, attachments, customers, and roadmaps, Linear: Custom GraphQL Request runs any Linear GraphQL operation with your own document and variables.
Starting a workflow from Linear
This integration ships read and action nodes only, with no trigger node, so a Linear event cannot start a workflow yet. Use a scheduled workflow that polls with Linear: List Issues or Linear: Search Issues, filtered on an updated-at window, and act on what changed since the last run.
Troubleshooting
Every node returns an authentication error
There is no Test Connection button on the Linear connector
A node returns nothing, or says an id does not exist, and the id is definitely right
An issue id is rejected, or updates the wrong record
A large list query fails or times out
A node failed but the response says HTTP 200
A field is rejected as the wrong type
Requests start failing after a long loop over issues
A setting you need is not a field on the node
Related
The Linear MCP
What connecting Linear unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
Linear is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.