Menu

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.

Sign in to Linear and open Settings.
Open API in the settings sidebar. Some workspaces label this section Security and access instead.
Under Personal API keys, click Create key and give it a label that says where it will be used, such as Mattering Automations.
Copy the key value. Linear personal API keys start with lin_api_ and do not expire on their own.
Copy the key on its own, with no Bearer prefix. Linear's developer docs show an API key sample and an OAuth sample side by side, and the OAuth one reads Authorization: Bearer <token>. Bearer is correct for OAuth access tokens only. Sending it with a personal API key fails authentication on every node.
Mattering strips a leading Bearer from the stored value defensively, so a pasted OAuth-style value still works. Pasting the raw key is still the right thing to do.

Connect Linear to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Linear from the list.
Click Create new credential, paste your Linear personal API key, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Connect. All 35 Linear nodes appear in your canvas palette, 18 read nodes and 17 action nodes.
This connector has no one-click Test Connection button. Linear's API is a single GraphQL endpoint that accepts POST requests only, and the generic connection test sends a GET, so it would fail even with a perfectly good key. Verify with the read-only node below instead.

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
The usual cause is a Bearer prefix on the credential. Linear's personal API key goes in the Authorization header raw, and Bearer belongs to OAuth access tokens only, so a value copied from Linear's OAuth curl sample fails on every node. Mattering strips a leading Bearer defensively, so if you are still failing, the key itself is wrong: it may have been revoked, or copied with a trailing space or surrounding quotes. Create a fresh key under Settings > API > Personal API keys and update the credential.
There is no Test Connection button on the Linear connector
That is deliberate. Linear's API is a single GraphQL endpoint that accepts POST only, and the generic connection test sends a GET, so the button would report a failure for a working key. Run Linear: Get Current User on a canvas instead. It takes no parameters and names the account the key belongs to.
A node returns nothing, or says an id does not exist, and the id is definitely right
A personal API key can only see the workspace of the user who created it. An id from another Linear workspace is rejected as if it did not exist. Run Linear: Get Organization and Linear: List Teams with the same credential to confirm which workspace the key is actually pointed at, and create the key from the right account if it is the wrong one.
An issue id is rejected, or updates the wrong record
Pass the UUID. Linear accepts the human identifier such as ENG-123 in its own documented examples and it appears to work wherever a UUID does, but the UUID is the form confirmed for every id argument. Linear: List Issues, Linear: Search Issues, and Linear: Get Issue all return the UUID next to the identifier, so carry the UUID forward from the step that found the issue.
A large list query fails or times out
Linear caps a single GraphQL query at 10,000 complexity points, and complexity grows with page size and with how much each row expands. Lower the page size, or narrow the filter, before assuming the node is broken. The list nodes already leave nested collections such as labels and comments off each row for this reason. Use Linear: Get Issue for one issue's full record and Linear: List Issue Comments for its comments, rather than trying to pull everything in one page.
A node failed but the response says HTTP 200
That is normal for GraphQL. Linear returns HTTP 200 and puts the problem in an errors array rather than in the status code. The connector reads that array, fails the step deliberately, and surfaces the message on the node output, so read the error text there rather than assuming the request never arrived.
A field is rejected as the wrong type
GraphQL is strictly typed, so a priority field will not accept a quoted number and a boolean will not accept the text true. The connector converts values to the type each field declares and raises a clear node error when it cannot, which usually points at a templated value that arrived as text from an earlier step. Array fields such as label ids accept a JSON array. Check the upstream expression rather than the Linear node.
Requests start failing after a long loop over issues
Linear enforces hourly limits on request count and on total query complexity, and the numbers differ by authentication type and plan. Its rate limiting documentation is the source of truth, and it is worth reading rather than assuming: Linear's own docs quote two different request-per-hour figures for API keys in different places. The connector does not back off on your behalf, so pace loops that call list nodes repeatedly, or narrow the filter instead of polling in a tight loop.
A setting you need is not a field on the node
Each typed node carries a fixed GraphQL document containing only the arguments Linear's published schema documents, because an undocumented argument fails validation and breaks the whole operation rather than just that field. Use the node's extra variables object to pass input-object fields it does not expose individually, and Linear: Custom GraphQL Request for anything that needs a different operation entirely, including initiatives, documents, attachments, and customers.

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.

Start Free Explore our Products