Linking members to Linear

By the end of this page every member who files tickets is linked to the right Linear user, so their tickets go to their own team and are assigned to them. The bot matches by name first, and you fix what it is unsure about.

Before you start

You need the Manage Server permission. Without it the bot replies You need Manage Server.
LINEAR_API_KEY, the key that connects the bot to Linear, must be set. /linear-admin exists whenever it is set, even with ticket prompts off, and is missing without it. See Configuration.
Every reply is private and pings nobody.
Members cannot link themselves.

What a link does

A link changes the member’s ticket prompt:

Member	Teams in the form	Assignee
Linked, on one Linear team	That team. No team field	The member
Linked, on several teams	Those teams only	The member
Linked, on no team	All public teams	The member
Not linked	All public teams	No one

Private teams are offered only to a member of them, so the Linear key must be able to create issues in those teams too. If the linked Linear user is later deactivated, the member is offered all public teams, and Linear may refuse the assignee, in which case the ticket is filed unassigned.

The bot keeps each team list for 60 seconds, so a team change in Linear can take about a minute to reach the form.

A link also decides who may change an existing ticket from a meeting. An action item that updates a ticket, such as moving it to In Progress, is applied only when the person pressing the button has a link made by an admin with /linear-admin link and is a member of that ticket’s team. A link made by name matching does not count, because anyone can copy a display name. An unlinked member, or one on another team, is refused with a line saying why and nothing changes. A ticket in a private team is never changed by a meeting.

How the bot matches by itself

The bot compares each member’s server display name (the name other members see for them in this server) with each Linear user’s name and display name. Case, accents and extra spaces do not matter. Nothing else does: no first-name-only, partial or close match, because a wrong match would assign tickets to the wrong person.

A member is linked automatically only when the match is one-to-one: exactly one Linear user has that name, and no other member has it. If two members share a name, or one member matches two Linear users (for example a member called Jo, when two Linear users both have the display name Jo), the bot marks them unsure and links nobody.

It runs:

Once when the bot starts, after it has loaded the member list.
Each time you run /linear-admin list or /linear-admin sync.
When a member who is not linked submits a ticket form. Only that member is matched then.

A member you have linked or unlinked yourself is never matched again. Members who have left the server are not matched and do not appear in the report.

The bot reads at most the first 100 active Linear users and keeps the list for 60 seconds. In a larger workspace, users past the first 100 cannot be matched or chosen with link, and a new Linear user can take a minute to show up. Linear apps (integration accounts, not people) and deactivated users are never listed.

Check who is linked

Run /linear-admin list. It matches first, so the report is current. /linear-admin sync does the same and starts with Matched N members by name.

You type

/linear-admin list

Doge Bot replies

Linked (2)
<@123456789012345678> - Sam Rivera (matched by name)
<@234567890123456789> - Alex Doe
Unsure (1)
<@345678901234567890> - could be: Jo Lee, Jo Leigh
No match (1)
<@456789012345678901>
Not matched on purpose (0)

Only you can see this

The four sections:

Section	What to do
`Linked`	Check the names are right. `(matched by name)` means the bot made the link. A link you made has no note. `a Linear user` in place of a name means that Linear user is no longer in the active list
`Unsure`	The member matched more than one Linear user, or another member matched the same one. `could be:` lists the matching Linear users. Pick the right one for each, as below
`No match`	No Linear user has this member’s name. Link them if they have a Linear account under another name. Leave them if not: they choose from all public teams
`Not matched on purpose`	Members you unlinked, including members who had no link. The bot leaves them alone

The list is cut at about 1950 characters and ends with ...and N more lines. No match shows 20 members, then and K more.

Fix an unsure or missing member

Run /linear-admin link. Choose the member, then type a name in linear_user and pick from the up to 25 active Linear users it suggests, shown as Name (display name) or just the name when both match. What you type is matched anywhere in that text. The list is empty when Linear cannot be reached. The reply names the Linear user and the teams the member’s tickets go to:

You type

/linear-admin link member: @Sam linear_user: Sam Rivera

Doge Bot replies

Linked <@123456789012345678> to Linear user Sam Rivera. Their tickets go to: Engineering, Tools.

Only you can see this

A Linear user on no team gives They are not on any Linear team, so they choose from all public teams. instead.

Linking a member who already has a link replaces it. If another member holds that Linear user, the reply is That Linear user is already linked to <@234567890123456789>. Unlink that member first.

Undo a link

/linear-admin unlink with the member. The reply is Unlinked <@123456789012345678>. The member goes back to choosing from all public teams, their tickets are unassigned, and the bot does not match them by name again. This holds even for a member who had no link: they move to Not matched on purpose. If the bot has no record of the member yet, it answers <@member> was not linked. and changes nothing. Use /linear-admin link to link them later.

If something looks wrong

You see	Why
`Could not reach Linear. Try again in a moment.`	Linear did not answer, rate limited the bot or refused its key. Try again, and check the key if it keeps happening
`Pick a Linear user from the list.`	The `linear_user` value was typed, not chosen from the suggestions
A ticket was filed but not assigned	The member is not linked, or Linear refused the assignee. See Troubleshooting
`/linear-admin` is missing	`LINEAR_API_KEY` is not set

Every reply is on Commands, the matching rule on Ticket prompts and what the bot keeps on Data.

Rolling out the bot for the order to turn things on.
Ticket prompts for what members see.