How to connect the Linear integration
Last updated October 15, 2026
Overview
The Linear integration links Atlas tickets with Linear issues, so support and engineering stay in sync. Agents create a Linear issue from a ticket, or link one that already exists. When the issue is completed or canceled in Linear, Atlas can reopen the ticket so the agent can update the customer.
An Admin connects Linear once for the whole workspace, adds a webhook in Linear, and chooses which teams to monitor, when tickets reopen and which activity syncs between Atlas and Linear.
Key Features
- Ticket and issue linking: Create a new Linear issue from a ticket, start from a Linear template, or link an existing issue.
- Monitored teams: Monitor all Linear teams or only specific ones.
- Automatic reopen: Reopen Snoozed or Pending tickets when the linked issue moves to Completed or Canceled in Linear.
- Two-way activity sync: Choose which Atlas activity creates activity in Linear, and which Linear activity creates activity or internal notes in Atlas.
- Template placeholders: Fill customer details, like name and email, into your Linear templates automatically.
How to connect the Linear integration
Connect your Linear account
- Go to "App Configuration > Integrations > Linear" and click "Connect Linear".
- Review the access Atlas is requesting and click "Authorize".
- You are returned to Atlas. The message "Linear installed successfully" confirms the connection.
Add the webhook in Linear
After connecting, Atlas shows "Action Required: Configure a webhook in Linear to complete the integration." Atlas needs this webhook to receive updates to issues and comments.
- Click "Show setup instructions" and copy the webhook URL.
- In Linear, create a new webhook:
- Label: A name you'll recognize, for example "Atlas".
- URL: Paste the webhook URL you copied from Atlas.
- Events: Select "Projects", "Issues" and "Comments".
- Click "Create webhook".
- Back in Atlas, dismiss the notification.
Configure monitored teams and ticket reopening
- Open the "Monitored Teams" dropdown (it shows "All" by default) and choose an option:
- "All": Atlas monitors every Linear team.
- "Specific": Open "Select teams" and choose one or more teams.
- Turn on "Use config to know whether to reopen tickets".
- Choose which ticket statuses can be reopened, for example "Snoozed" and "Pending". Leave "Closed" unchecked to keep closed tickets closed.
- In "When a Linear issue moves into", choose the Linear states that reopen the ticket, for example "Completed" and "Canceled".
Choose which activity syncs
Under "Automations", choose the events that create activities and notes in Atlas and Linear:
| Setting | What it does | Options |
| Create activities in Linear when | Atlas activity that's added to the linked Linear issue. | Change in priority, change in status, new customer message, new agent message, change in tags, new internal note |
| Create activities in Atlas when | Linear activity that's added to the linked Atlas ticket. | Change in priority, change in status, change in assignee |
| Create internal notes in Atlas | Linear activity that's saved as an internal note on the ticket. | New comment |
Map Linear placeholders (optional)
Placeholders fill Atlas fields into your Linear templates, so new issues include customer details automatically.
- Under "Linear placeholders", click "Add placeholder".
- Enter the placeholder name you use in your Linear template. For example, "customer_name".
- Open "Select Atlas field" and choose the field. For example, "customer.full_name".
- Click "Save". The message ""{{customer_name}}" placeholder mapping was successfully added!" confirms it. For example: Linear placeholder Atlas field {{customer_name}} customer.full_name {{customer_email}} customer.email
- Click "Save". The message "Linear settings updated successfully" confirms your configuration.
How to link a ticket to a Linear issue
Agents link tickets from the inbox once Linear is connected.
Create a new Linear issue
- In the "Inbox", open the ticket and click "Link issue" in the side panel.
- Optional: Click "Apply Linear template" and choose a template. Its description can include your placeholders, so customer details are added for you.
- Enter the "Title" and choose the "Team", "Assignee", priority and labels.
- Click "Create issue". The message "Linked a new Linear issue [issue key] to ticket #[number]" confirms the link.
The linked issue appears on the ticket. Click it to open the issue in Linear.
Link an existing Linear issue
- Open the ticket and click "Link issue".
- Choose "Link", then search for and select the issue.
- The message "Linked Linear issue [issue key] to ticket #[number]" confirms the link.
Unlink an issue
Open the ticket and click the "X" next to the linked issue. The message "Unlinked Linear issue [issue key] from ticket #[number]" confirms it.
FAQs & Troubleshooting
Why didn't my ticket reopen when the Linear issue was completed?
Check the following:
- The webhook is created in Linear, with "Issues" selected.
- "Use config to know whether to reopen tickets" is on, and the ticket's status (for example, Snoozed or Pending) is selected.
- The Linear state the issue moved into is selected in "When a Linear issue moves into".
- The issue belongs to a monitored team.
Why don't Linear comments appear in Atlas?
Check that the webhook includes "Comments", and that "new comment" is selected under "Create internal notes in Atlas".
Why is a placeholder empty in the Linear issue?
The placeholder name must match the name in your Linear template exactly, and it must be mapped to an Atlas field under "Linear placeholders".
Can I link a ticket to an issue that already exists?
Yes. Click "Link issue", choose "Link" and select the existing issue.