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.
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
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.
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.
Add Linear ticket sync
Click Add ticket sync, then select Linear in the Add Ticket Sync for <department> dialog.
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.
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
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.
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.
Test Risotto to Linear sync
Verify that tickets flow from Risotto to Linear:
- Create a test ticket in Risotto (via Slack or the dashboard)
- Open your Linear team's issue list
- Confirm the issue appears with the correct team and labels
Test Linear to Risotto sync
Verify that the bidirectional sync is working:
- Add a comment on the Linear issue you just created
- Confirm the comment appears on the corresponding Risotto ticket
- Change the issue status in Linear
- Confirm the status updates in Risotto
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. 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.
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:
- 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.
- Risotto sets the old issue to the Done state. The old issue stays in the old team for reference.
- 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.
Something wrong or missing? Report an issue · View as Markdown