# Linear

Configure Linear issue tracking integration with Risotto for bidirectional ticket sync

Risotto integrates with Linear to provide bidirectional ticket synchronization. Risotto creates a Linear issue for each synced Risotto ticket. After that, status updates, comments, attachments, and labels sync in both directions.

> **Warning:** You must have **Admin** permissions in your Linear workspace to set up this
> integration. See [Linear's roles documentation](https://linear.app/docs/roles)
> for details.

## Prerequisites

Before setting up the Linear integration, ensure you have:

- Admin access to your Linear workspace
- A Risotto account that can change the department's settings: an Org Admin, a Manager, or a Supervisor of the department
- At least one department configured in Risotto

## Setup Process

1. **Create a Linear API key**

   In Linear, create a personal API key. Risotto uses this key to create and update issues in your Linear workspace.

2. **Open the department's Ticket Sync page**

   In your Risotto dashboard, go to **Settings**. Under **Departments**, click the department you want to sync with Linear, then click **Ticket Sync**.

   > **Tip:** Start with a single department to verify your configuration before rolling
   > out to additional departments.

3. **Add Linear ticket sync**

   Click **Add ticket sync**, then select **Linear** in the **Add Ticket Sync for \<department>** dialog.

   *Product example: The Add Ticket Sync for IT dialog, listing the ticketing integrations, with Linear ringed.*

   **Add ticket sync** shows only while the department has no ticket sync. A department syncs with one ticketing system: to switch a department to Linear, first disconnect its current sync.

4. **Enter your Linear details**

   In the **Configure Linear for \<department>** dialog, fill in these fields, then click **Save**:

   - **API Key**: the Linear API key you created
   - **Team Name**: the name of the Linear team to create issues in
   - **Labels** (optional): comma-separated Linear labels to apply to new issues

   *Product example: The Configure Linear for IT dialog, with the API key, the team IT and two labels filled in, and Save.*

   When you save, Risotto registers a webhook on the team so that changes in Linear come back to Risotto. If Risotto can't find the team, the error shows under **Team Name**.

5. **Turn on sync**

   The **Ticket Sync** page now shows the department's sync settings and a **Linear** card with the **Team** and **Labels**. Make sure **External ticket sync enabled** is on.

   *Product example: The IT department's Ticket Sync page with Linear connected to the team IT, and External ticket sync enabled.*

6. **Test Risotto to Linear sync**

   Verify that tickets flow from Risotto to Linear:

   1. Create a test ticket in Risotto (via Slack or the dashboard)
   2. Open your Linear team's issue list
   3. Confirm the issue appears with the correct team and labels

7. **Test Linear to Risotto sync**

   Verify that the bidirectional sync is working:

   1. Add a comment on the Linear issue you just created
   2. Confirm the comment appears on the corresponding Risotto ticket
   3. Change the issue status in Linear
   4. Confirm the status updates in Risotto

   > **Note:** An issue that you create directly in Linear does not become a Risotto
   > ticket. Risotto syncs only issues that it created for a Risotto ticket.

## Features

Once configured, the Linear integration provides:

- **Bidirectional Sync** -- Risotto creates a Linear issue for each synced ticket, and changes on that issue sync back to the Risotto ticket
- **Status Synchronization** -- status changes in one system are reflected in the other
- **Comment Sync** -- comments added in either system appear in both places
- **Attachment Sync** -- file attachments (including those on comments) are synced between systems
- **Label Support** -- configure Linear labels in Risotto that are automatically applied to new issues
- **Team Mapping** -- route issues to the correct Linear team per department

## Department Configuration

Each department has its own Linear sync, set up on its **Ticket Sync** page as in [Setup Process](#setup-process). To change the API key, team, or labels later, open the **Connected** menu on the **Linear** card and click **Configure...**. To stop syncing, click **Disconnect...** in the same menu.

The rows above the **Linear** card apply to the department's sync:

- **External ticket sync enabled** turns the sync for the department on or off.
- **Only sync escalated tickets**: by default, Risotto creates a Linear issue for every request in the department, including requests that the agent resolves. Turn this on to create an issue only when a ticket escalates.
- **Share ticket URL with requestor** shares the Linear issue's URL with the requester when their request escalates.
- **Show external ticket ID** shows the Linear issue ID in the request channel. It is on by default.

If your team already creates Linear issues from Slack with another tool (for example, Linear Asks), turn that tool off for the channels where Risotto answers. Otherwise each request gets two Linear issues.

> **Note:** Each department syncs with one Linear team. Different departments can sync
> with different Linear teams. Labels are added to the issue, but they do not
> choose the team. To send tickets to more than one Linear team, create one
> department for each team.

### Issue assignee

When Risotto creates or updates a Linear issue that has no assignee, it assigns the issue to the person assigned to the Risotto ticket. If the ticket escalated and no person is assigned, Risotto assigns the department's escalation contact. Risotto matches the person to a Linear user by email. If no Linear user has that email, or the escalation contact is a user group, the issue stays unassigned.

Risotto does not change an assignee that is already set in Linear. A change of assignee in Linear does not sync back to Risotto.

### How comments appear in Linear

- Risotto posts the first synced comment as a top-level comment on the Linear issue. Later comments from Risotto are replies to that comment, so the conversation stays in one thread.
- If someone deletes that first comment in Linear, Risotto posts the next comment as a new top-level comment. Later comments reply to the new one.
- Each comment starts with a line that names the author of the synced message, for example `From Jane Doe:`. Linear shows the owner of the API key as the person who posted the comment. The key owner is also the creator of every issue that Risotto creates. Risotto does not support a separate bot identity in Linear, because it connects with a personal API key.
- Internal comments in Risotto do not sync to Linear.
- If **Only sync escalated tickets** is on, Risotto adds the messages from before the escalation as separate top-level comments. Messages after the escalation go into one thread.

### Moving a ticket to another department

When you move a ticket to a department that syncs with a different Linear team, Risotto does not move the Linear issue:

1. Risotto adds a comment to the old Linear issue. The comment says that the ticket moved to the new department, with a link to the Risotto ticket.
2. Risotto sets the old issue to the **Done** state. The old issue stays in the old team for reference.
3. Risotto creates a new issue in the new department's Linear team. If the new department syncs only escalated tickets, Risotto creates the issue when the ticket escalates.

Before you confirm the move, the dashboard shows which issue it closes and where it creates the new one. Escalation does not change the department of a ticket. To move a ticket, change its department in the dashboard or with the move option on the ticket card in the agent channel.

## Troubleshooting

### Authorization fails or Linear doesn't connect

- Ensure you have Admin permissions in your Linear workspace
- Check that the API key is valid and not revoked
- On the department's **Ticket Sync** page, open the **Connected** menu on the **Linear** row, click **Configure...**, and enter a new **API Key**

### Issues not syncing from Risotto to Linear

- Verify that **External ticket sync enabled** is on in the department's **Ticket Sync** page
- Check that the **Team** value on the **Linear** row matches your Linear team name
- Confirm the API key is still valid in Linear

### Issues not syncing from Linear to Risotto

- Ensure the Linear team is mapped to a department in Risotto
- Check that the issue was created in a team with an active sync configuration
- Verify webhook connectivity -- Linear sends updates to Risotto via webhooks automatically

### Comments or attachments not syncing

- Confirm bidirectional sync is active (not just one-way)
- Check that attachments are within size limits
- Try adding a new comment to verify sync is working for new activity

### Labels not applied to new issues

- Verify the labels configured in Risotto match existing labels in your Linear team
- Label names are resolved automatically -- check for typos or renamed labels
- Labels are only applied when issues are created, not retroactively

### Status not mapping correctly

- Risotto has no status mapping settings for Linear
- When Risotto resolves or closes a ticket, it moves the Linear issue to the team's **Done** state
- Make sure your Linear team has a workflow state named **Done**
- When an issue's state changes in Linear, Risotto sets the ticket by the state's type: a completed or canceled state resolves the ticket, a started state sets it to **In progress**, and any other state sets it to **Open**. Deleting the issue closes the ticket.

Source: https://www.tryrisotto.com/docs/integrations/ticketing/linear
