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
Get your credentials
- Serval-managed OAuth app (recommended)
- Bring your own Linear OAuth app
Connect in Serval
Choose whether to allow customer access
Choose whether to allow initiative access
Choose how to connect
Serval-managed: authorize on Linear
Your own app: fill in the form
- 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”.
Complete the authorization on Linear
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.
Gotchas and troubleshooting
Customer requests fail with a missing-scope error
Customer requests fail with a missing-scope error
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.Creating an initiative fails with a missing-scope error
Creating an initiative fails with a missing-scope error
Workspace membership management requires Linear Admin
Workspace membership management requires Linear Admin
Issues and comments are attributed to the original requester
Issues and comments are attributed to the original requester
A Linear team or sub-team is missing from Serval's team list
A Linear team or sub-team is missing from Serval's team list
Bring-your-own app: the Callback URL must match exactly, and the secret is shown once
Bring-your-own app: the Callback URL must match exactly, and the secret is shown once
"Invalid or expired OAuth state" during a bring-your-own connection
"Invalid or expired OAuth state" during a bring-your-own connection
Tokens refresh automatically - with one hard failure case
Tokens refresh automatically - with one hard failure case
SLA timestamps only apply to unstarted or started issues
SLA timestamps only apply to unstarted or started issues
Need help? Contact support@serval.com for assistance with your Linear integration.

