Skip to main content

​
About Linear

Linear is a modern project and issue tracking tool designed for software development teams. It offers streamlined workflows, fast performance, and integrations that help engineering teams plan, track, and ship products efficiently.

​
Two Linear apps

Serval connects to Linear through two separate apps. Linear’s API requires elevated admin permissions to manage workspace membership, and those permissions are incompatible with the way Serval attributes synced tickets and comments to the original user. To keep both working correctly, the two concerns are split into two apps you connect independently:
AppUse it forLinear permissions
LinearTicket syncing and issue automation workflows: create/update/archive issues, add comments and labels, set priorities and projects. Tickets and comments are attributed to the original requester.Read + write
Linear AdminAccess provisioning: granting and revoking a person’s access to your Linear workspace through Serval [invite as Admin or Member, suspend on deprovision].Read + write + admin
You can connect one or both, depending on what you need:
  • Only syncing tickets / running issue workflows? Connect Linear.
  • Want Serval to grant and revoke Linear workspace access [access requests, automated provisioning/deprovisioning]? Connect Linear Admin.
  • Doing both? Connect both. They can point at the same Linear workspace and operate independently.
Access requests for Linear are served by the Linear Admin app. The Linear app is for ticket syncing and workflows only. If you only connect Linear, access requests for Linear cannot be provisioned.

​
Prerequisites

  • Linear [ticket sync]: you must be able to authorize applications in your Linear workspace.
  • Linear Admin [access provisioning]: the person who authorizes the connection must be a workspace admin in Linear. Linear only allows admins to invite or suspend members, so a non-admin authorization will fail when Serval tries to provision access.

​
Connecting the Linear app [ticket syncing]

  1. In Serval go to Apps → Available → Linear → Connect.
  2. Choose Sign in with Linear to use the Serval-managed OAuth app [recommended], or Use your own Linear OAuth app to bring your own [see Bring your own Linear app].
  3. Review and accept the permissions on Linear’s authorization page, then click Authorize.
  4. You’ll be redirected back to Serval with the integration connected.
No additional configuration is required for the connection itself. To start syncing, see Ticket Syncing below.

​
Connecting the Linear Admin app [access provisioning]

  1. In Serval go to Apps → Available → Linear Admin → Connect.
  2. Choose Sign in with Linear (Admin) to use the Serval-managed OAuth app [recommended], or Use your own Linear OAuth app [see Bring your own Linear app].
  3. Authorize as a workspace admin. Linear will ask you to grant admin access to your workspace; this is required for Serval to invite and suspend members.
  4. You’ll be redirected back to Serval with the Linear Admin app connected.
Once connected, Linear access requests in Serval are provisioned and deprovisioned automatically through this app. Members can be granted the Admin or Member role.
After connecting, run the Verify Linear Admin Access health check on the Linear Admin app. It confirms the connection actually has admin permissions, so a misconfigured authorization is caught before the first access request rather than during one.

​
Ticket Syncing

Serval can sync tickets with Linear issues so your team can work in their preferred tool while keeping visibility across systems. Ticket syncing uses the Linear app.

​
Step 1: Enable Ticket Syncing

1

Turn on ticket syncing

Navigate to the Linear app settings in Serval and enable the ticket syncing toggle to allow Serval to sync tickets with Linear issues.

​
Step 2-5: Configure Sync Settings

Once ticket syncing is enabled, complete the remaining configuration steps in Serval:
  1. Select Linear Team - Choose which Linear team to sync issues with
  2. Status Mapping - Map each Serval status to a corresponding Linear state
  3. Additional Fields - Configure default values for additional fields and optionally allow Serval to set fields using AI
  4. Sync Strategy - Configure how and when tickets should be synced
For general information on sync behavior and best practices, see Syncing to Your Ticketing System.

​
Access provisioning

Serval can grant and revoke access to your Linear workspace as part of access requests and automated access management. Provisioning uses the Linear Admin app.
  • When a request is approved, Serval invites the user to the Linear organization with the requested role [Admin or Member].
  • On deprovision, Serval suspends the user in Linear.
Because these actions require admin permissions, make sure the Linear Admin app was authorized by a workspace admin [see Connecting the Linear Admin app].

​
Bring your own Linear app

Instead of the Serval-managed OAuth app, you can connect with a Linear OAuth application your workspace owns [required for self-hosted deployments]. The flow is the same for both the Linear and Linear Admin apps:
  1. In the connect dialog, choose Use your own Linear OAuth app.
  2. Copy the Callback URL shown in the dialog.
  3. In Linear, open Settings → API → Applications and create an OAuth application [or edit an existing one]. Paste the callback URL into the application’s Callback URLs. Linear requires an exact match.
  4. Copy the application’s Client ID and Client secret back into Serval and connect.
The Linear app and the Linear Admin app use different callback URLs. Use the exact value the dialog shows for the app you’re connecting, and add it to your Linear OAuth application’s Callback URLs. Reusing the wrong app’s callback URL produces an “Invalid redirect_uri” error from Linear.
For the Linear Admin app, the same workspace-admin requirement applies: authorize the OAuth app as a Linear workspace admin so it can be granted admin access.
Anything defined in the Linear API can be accessed through Serval. Need help? Contact support@serval.com for assistance with your Linear integration.