Connecting Linear

What the Linear integration does

Every new comment on a project you send to Linear becomes a Linear issue, with the screenshot, the page and the browser details it was left with. When the issue moves in Linear, the comment's status follows, and when you change the status in Huddlekit, the issue moves too. For an overview, see the Linear integration page.

Before you start

• Plan — Linear is on the Team plan. See Understanding plans and pricing.
• Role — only workspace owners and admins can connect Linear and change its settings. Other members can open Integrations and see that Linear is connected, but can't change anything.

Connect Linear

1. Open Integrations in your workspace sidebar.
2. Find Linear under Apps and click Connect.
3. Approve access on Linear's consent screen.

You're returned to Huddlekit with a Linear connected message. On a new connection it adds "Nothing syncs until you choose a team for your projects." Nothing is sent to Linear until you do the next step.

Issues are created by the Huddlekit app in Linear, not under the name of the admin who connected it.

Choose where comments go

Click the ⋯ button on the Linear row and choose Configure to open Linear settings.

• Default team — used for every project you don't set individually, including projects created later. Choose No default if only the projects you pick should sync.
• Projects — every website, web app and media project in the workspace is listed. A project set here wins over the default. Pick a team, leave it on Default (team name), or choose Don't sync to keep it out of Linear even when a default is set. Without a default team, the first choice reads Not synced.

Changes save as you make them. They only affect new comments: issues already created stay where they are and keep their status in sync, even if you later set their project to Don't sync or remove the default. To stop existing issues syncing, disconnect.

Comments left while a project has nowhere to go, including before you first pick a team, aren't sent later. Each one gets an issue the next time its status changes, if its project has a team by then.

Map statuses

Each team has its own status map, shared by every project that sends comments to it. Click the gear button next to the default team or a project to open Status mapping, then choose a Linear state for each Huddlekit status.

When a team is first used, Huddlekit fills in a starting map from Linear's state types:

Hover over the ⓘ next to Open to see them, for example "Also becomes Open when an issue moves to Backlog or Triage in Linear."

In review is left for you to map, because Linear has no state type that means "in review". Until you map it, the team is flagged with Status mapping incomplete, and moving a comment to In review doesn't move its issue. An unmapped status shows Never sync this status in the picker. A status left on it doesn't sync in either direction, extra states included, but the team stays flagged until every status is mapped.

A state nobody mapped never changes a comment. Linear's canceled states start unmapped, so canceling an issue leaves the comment's status alone unless you map a canceled state yourself. Your client isn't told their feedback is resolved when it was declined.

If two Huddlekit statuses point at the same Linear state, an issue moved into that state sets the comment to the earlier of the two, in the order Open, In review, In progress, Resolved.

What each issue contains

• Title — the comment number and the first line of the comment, such as #12 — Logo is blurry on retina. When the issue goes to the default team, or to a team more than one project is routed to, the title starts with the project name in brackets.
• Description — the full comment text, the project, who left the comment and where, the screenshot, the browser details, and an Open in Huddlekit link back to the comment.

What "where" and "browser details" contain depends on the project:

• Website — a link to the page, and the OS, browser, resolution, viewport, pixel ratio, color depth and network.
• Web app — the page, and the OS, browser, viewport and pixel ratio.
• Media — the page number, or the time in a video. Media comments have no screenshot or browser details.

The comment's first line is cut at 80 characters, and the number and any project name go in front of it.

A new comment usually reaches Linear within a minute. Huddlekit holds it for about ten seconds first, so the screenshot is usually ready in time. For a web app comment, Open in Huddlekit opens the page in your own app where the comment was left. Private comments are sent too: they're hidden from guests, not from your team.

What syncs and what doesn't

Status is the only thing that syncs both ways.

• The issue description is written once, when the comment arrives. Editing the comment's text, or a screenshot arriving later, doesn't update the issue.
• Replies, priority, tags, assignees and attachments stay in Huddlekit. Comments your team writes in Linear stay in Linear.
• Deleting a comment in Huddlekit doesn't delete its issue.
• Comments left before you connected aren't sent in bulk. An older comment gets an issue the next time its status changes, if its project has a team by then.

Once a night, Huddlekit compares linked issues with their comments and repairs any status that didn't sync. If only the issue moved, the comment follows it, unless the connection is set to one-way sync. If the comment changed since it last synced, Huddlekit resets the issue to match and leaves a comment on the issue explaining why. Huddlekit holds the client's feedback, so its status wins. If the comment's status isn't mapped (In review, by default), both are left alone.

One-way or two-way sync

New connections sync both ways. To keep changes made in Linear from coming back to Huddlekit, click ⋯ on the Linear row and choose Switch to one-way sync. Status changes in Linear then stay in Linear, including during the nightly check. Comments still become issues, and status changes in Huddlekit still move them. Choose Switch to two-way sync to turn it back on. Reconnecting the same Linear workspace keeps whichever you chose.

Disconnecting

Click ⋯ on the Linear row and choose Disconnect. Huddlekit's access to Linear is revoked, and the issues already created stay in Linear. If anything is left for you to remove in Linear, the Disconnected from Linear message says so and stays until you close it, for example "Remove Huddlekit from your Linear settings to finish."

If you connect the same Linear workspace again later, your teams, routing, status maps and the links between comments and issues come back, so existing comments don't get duplicate issues.

If your plan changes

Linear syncs only while the workspace is on an active or trialing Team subscription. If the workspace moves to another plan, or a payment is past due, the Linear row shows Paused:

• Nothing is sent to Linear and nothing comes back. Comments left while paused aren't sent later, but each one gets an issue the next time its status changes.
• Your settings are kept, and Disconnect stays available.

Once the workspace is back on Team, the nightly check repairs issues that already exist. If a comment's status changed during the pause, its issue is reset to match, with a comment explaining why. If only the issue moved, the comment follows it, unless the connection is set to one-way sync.

Troubleshooting

If connecting doesn't finish, you're returned to Integrations with a Linear not connected message and the reason:

• Cancelled. Nothing changed. — you cancelled on Linear's screen. Click Connect again when you're ready.
• That Linear account has no teams. — create a team in Linear, or approve access with a Linear account that has one.
• Could not read your teams. Check the app has access. — click Connect again and approve access when Linear asks.
• That link expired. Start again. — more than ten minutes passed on Linear's screen. Click Connect again.
• You switched accounts partway. Sign back in and retry. — you were signed in to Huddlekit as someone else by the time you came back. Sign in as the admin who started, then connect again.
• That link was already used. Start again. or That link was not valid. Start again. — click Connect again from Integrations.
• Only workspace admins can do this. or Needs the Team plan. — ask an owner or admin, or upgrade the workspace first.
• Anything ending in Try again. — click Connect again.

Once connected:

• Not configured on the Linear row means no project is sent anywhere yet. Choose a default team or a team for a project.
• Status mapping incomplete means a Huddlekit status has no Linear state. Click the flagged row's gear button to map it.
• Sync failing on the Linear row means a comment couldn't be sent to Linear and won't be retried. Open Configure from the ⋯ menu and hover over Sync failing at the top of the dialog for the reason, such as "Linear no longer accepts Huddlekit. Reconnect Linear." It clears once a comment syncs to Linear again.
• If a team was deleted in Linear, or Huddlekit can no longer see it, the settings name the team and ask you to point its projects at another one.
• If Linear settings shows One-way sync and you didn't choose it, choose Switch to two-way sync in the ⋯ menu. If the badge's tooltip asks you to reconnect, choose Reconnect instead. Your mappings are kept.