Skip to main content

About Linear

Linear is the issue tracker many engineering and product teams use to plan and ship work. Serval’s Linear integration connects to your Linear workspace so Serval tickets and Linear issues stay in sync - with comments attributed to the original requester rather than a generic app identity - and ships 15 installable workflows for issue management and workspace lookups. All traffic goes to Linear’s GraphQL API (host: api.linear.app). Authentication: OAuth 2.0 - sign in with the Serval-managed Linear OAuth app (recommended), or bring your own Linear OAuth application. Both modes request read and write by default. Select Allow access to Linear Customers to also request customer:write, which includes reading and writing customer data. Select Allow access to Linear Initiatives to also request initiative:write, which includes reading and writing initiatives. Both options are off by default. Tokens are refreshed automatically. Data sync: Two-way ticket syncing runs in the background once a Linear team is connected as a ticket channel: Serval regularly checks the team for new and updated issues and comments and pulls them in, and pushes Serval-side changes out to Linear as they happen. Workflow actions run on demand, calling Linear at the moment they run.

What the Linear integration enables

Anything defined in the Linear API can be accessed through Serval.

Get your credentials

Connect in Serval

1

Choose whether to allow customer access

If your workflows need to read or manage Linear Customers or attach customer requests to issues, select Allow access to Linear Customers. Leave it unchecked for the default read and write permissions. This option applies to both connection methods and requests customer:write, which includes customer reads and writes. See Linear’s customer access scopes.
2

Choose whether to allow initiative access

If your workflows need to create or update Linear initiatives, select Allow access to Linear Initiatives. This option applies to both connection methods and requests initiative:write, which includes initiative reads and writes. Linear’s general write permission does not cover initiatives. See Linear’s initiative access scopes.
3

Choose how to connect

The connect dialog offers two options: “Sign in with Linear (OAuth)” (tagged “Recommended”) - “Connect using the Serval-managed Linear OAuth app.” - and “Use your own Linear OAuth app” - “Connect with a Linear OAuth application owned by your workspace.”
4

Serval-managed: authorize on Linear

Click Sign in with Linear (OAuth) and approve the request on Linear’s consent screen. Serval connects as a Linear app user, and the consent screen’s Team access section sets which teams that app user can access: All public teams (the default) or Only select teams…, where you pick them one by one. Only those teams appear in Serval. That covers the ticket-sync team picker, the List Linear Teams workflow and health check, and Catalyst. Grant every team you plan to sync or create issues in, including sub-teams. A Linear admin can change the list later from Serval’s entry under Settings → Administration → Applications in Linear. If the sign-in can’t start, the dialog shows “Failed to initiate Linear OAuth” - try again or contact support.
5

Your own app: fill in the form

The custom-app form contains:
  • Callback URL - read-only, with a Copy button. Register this value on your Linear OAuth application before connecting.
  • Display name (optional) - “A friendly name shown in Serval - you choose this.” Placeholder: “My Company Linear”.
  • Client ID (required) - “Found on the application’s settings page in Linear, under OAuth.” Serval rejects a blank value with “clientId is required”.
  • Client secret (required, hidden as you type) - “Linear only shows this once when the app is created - if you don’t have it, regenerate the secret on the application’s settings page.” Serval rejects a blank value with “clientSecret is required”.
The Connect button stays disabled until both required fields are filled in. If the connection can’t start, you’ll see “Failed to initiate custom Linear app”.
6

Complete the authorization on Linear

Approve the request on Linear’s consent screen. Its Team access section sets the app user’s team access, as described in the Serval-managed step above - only the granted teams appear in Serval. You have 10 minutes from submitting the form - after that the attempt fails with “Invalid or expired OAuth state” and you must resubmit. If Linear rejects the exchange (for example, a mismatched Callback URL or wrong secret), you’ll see “Failed to exchange code for token”. On success, Serval records your Linear workspace name and ID as the connected instance.
Existing connections keep their current permissions. To add customer or initiative access, reconnect, select Allow access to Linear Customers or Allow access to Linear Initiatives, and approve the updated request in Linear. Serval restores both checkboxes from the permissions already granted when you reconnect.When reconnecting a bring-your-own-app install, the Display name and Client ID are pre-filled from your existing setup, but the Client secret is never pre-filled - re-enter it (or regenerate it in Linear if you’ve lost it).

Verifying the connection

The Linear integration runs three health checks:
  • Test Linear Connection - verifies the integration is connected and the OAuth token is valid by reading a single user from your workspace.
    • Success: “Successfully authenticated with Linear (found [number] user)”
    • Failure: “Unable to authenticate with Linear. Please verify the integration is still connected and the OAuth token has not been revoked.”
  • List Linear Users - checks that Serval can read users from the connected workspace.
    • Success: “Successfully listed Linear users (sample size: [number])”
    • Failure: “Unable to list users from Linear. Please verify the integration has the read scope and has not been disconnected.”
  • List Linear Teams - checks that Serval can read at least one team from the connected workspace. A passing run shows no message on the Integrations page; its run result records every team the application can read. A team or sub-team that was never granted to Serval is absent from the ticket-sync team picker, which lists every granted team, so check the picker when a team seems to be missing in Serval.
    • Success: the run passes. Its result records “Serval can read [number] Linear teams: [team names]. A team or sub-team that is not among them has not been granted to the application Serval connects with. A Linear admin (a workspace owner on Enterprise plans) grants it in Linear under Settings > Administration > Applications.” with up to 8 names and a count of the rest, plus every granted team’s ID, key, name and private flag in the result data. The check reads up to 20 pages of 250 teams; a workspace that grants more than that gets an “at least [number]” count, the result is marked incomplete, and the message no longer treats an absent team as ungranted.
    • Failure: “No Linear team has been granted to the application Serval connects with, so Serval cannot list, sync or create issues in any team. Ask a Linear admin (a workspace owner on Enterprise plans) to grant teams to that application in Linear (Settings > Administration > Applications), then run this check again.” when Linear returns no teams, or “Unable to list teams from Linear. Please verify the integration has the read scope and has not been disconnected.” when the request fails.
All three checks exercise general read access only; they do not verify customer or initiative permissions. To verify either, run a workflow that uses it. If every check is green but a workflow that invites or suspends a workspace member fails, the cause is usually that this integration deliberately has no admin scope - see Workspace membership management requires Linear Admin under Gotchas and troubleshooting.

Gotchas and troubleshooting

If a workflow returns 403 customer:read or customer:write required, reconnect the Linear integration, select Allow access to Linear Customers, and complete authorization in Linear. The customer:write permission covers both reading customers and attaching customer requests to issues. The Linear Admin connector is not required for these operations.
The connection was made without initiative access. Reconnect the Linear integration, select Allow access to Linear Initiatives, and complete authorization in Linear.
Inviting and suspending users requires the companion Linear Admin integration. Enabling customer or initiative access on the standard Linear connection does not grant admin permissions. The older built-in access-provisioning workflows on this integration (invite with the Admin or Member role, suspend by email) still work for existing installs but are deprecated for new ones; their role mapping accepts only “Admin”, “Member”, or “User” - any other role name fails.
Serval connects to Linear in app-actor mode, which is what allows synced issues and comments to appear in Linear as the person who raised the ticket rather than as a generic app identity. This applies to both the Serval-managed and bring-your-own connection options.
Serval connects to Linear as an app user, and Linear shows an app user only the teams it has been granted. Those are the teams selected for the application when it was installed, plus any granted since. Every team list in Serval - the ticket-sync team picker, the List Linear Teams workflow and health check, and Catalyst’s team lookups - comes from that grant. A team Serval wasn’t given is simply absent rather than shown as an error. Reconnecting on its own doesn’t add it: the grant lives on the application’s page in Linear, and an app user can’t be added from a team’s Members page.To add the team, a Linear admin (on Enterprise plans, a workspace owner) opens Settings → Administration → Applications in Linear (the list of installed applications, not the API → Applications page where OAuth apps are created), selects the application Serval connects with (Serval for the Serval-managed app), and under App user → Team access adds the missing team (Only select teams… lists each granted team; All public teams and select other teams… adds restricted teams on top of the public ones), then clicks Update and confirms. Restricted and private sub-teams must be granted explicitly; access to all public teams doesn’t include them. Then reopen the team picker in Serval - nothing is cached, so the team appears on the next load.If a team a ticket source already syncs with is later revoked from that application or deleted in Linear, the team picker shows the warning “Linear no longer lets Serval access the selected team” and the step returns to Setup Required. That warning appears only after Serval has read Linear’s current team list, so the connection itself is intact; a dropped connection shows a load error instead. The picker still lists every team Serval can see. Choose another granted team, or ask a Linear admin to grant the team again on the Applications page.Ticket syncing uses one Linear team per ticket source. To create issues in a second team, grant it to Serval and use a workflow that creates the issue through the Linear integration, for example one built in Catalyst, instead of a second sync.
Linear requires an exact match between the Callback URL registered on your OAuth application and the one Serval uses during both authorization and token exchange, and it rejects relative URLs. Always copy the value from Serval’s connect dialog verbatim. Separately, Linear displays the client secret only once at app creation - if it’s lost, regenerate it on the application’s settings page and reconnect with the new value.
Submitted credentials are held for only 10 minutes while you complete Linear’s consent screen. If the window passes, the attempt fails with “Invalid or expired OAuth state”. Re-open the connect dialog and submit the form again, then complete the authorization promptly.
Serval refreshes OAuth tokens automatically shortly before they expire, and older long-lived tokens on Serval-managed connections are upgraded to refreshable tokens transparently. The one case that requires action: a bring-your-own-app connection whose token expires with no refresh token available fails with “custom Linear app access token expired and no refresh token available; reconnect required”. The fix is to reconnect the integration.
During ticket sync, SLA-breach timestamps are written to a Linear issue only when that issue is in an unstarted or started state. For issues in any other state, the timestamp is silently dropped rather than causing a sync error.
Linear authorization codes are single-use, and Linear expects OAuth credentials as form parameters in the request body. Tooling that tries a different credential style first and then retries will burn the code on the failed attempt, producing “invalid_grant: authorization code is invalid” even with correct credentials. Serval sends credentials correctly on the first attempt - this only matters if you debug the token exchange with your own tooling.

Need help? Contact support@serval.com for assistance with your Linear integration.