Linear in the Gmail panel

How access works

OrgOrg never holds a workspace-wide Linear key. It holds grants that people give it through Linear's own consent screen, and there are two kinds:

• A personal grant: a member connects their own Linear account. The panel reads issues with that member's visibility and writes as them. This is the grant that allows edits.
• The org grant: an OrgOrg administrator connects one Linear account for the whole workspace. Members who have not connected their own account read issues through it, read-only. They see exactly what that account can see in Linear, private teams included, so connect the org grant with an account whose visibility you are comfortable sharing.

The panel always prefers a member's own grant. The org grant is the fallback, and the panel says so on screen with a one-click way to connect their own account.

Any Linear workspace works. Each grant is scoped to the workspace the person picks on Linear's consent screen. A person who belongs to several Linear workspaces should pick the one whose notifications reach their work inbox; issues from another workspace read as "not visible with your Linear account".

Set up for your workspace (admin)

1. Make sure the CRM app is enabled for your OrgOrg workspace. The Gmail panel is part of it.
2. Open Settings, Connectors, find Linear under Developer and automation, and expand the row.
3. Click Connect to Linear. Linear opens in the same tab. Sign in if needed, pick the workspace, and allow the requested permissions.
4. You return to the connectors page. The row reads Connected and, once expanded, names the workspace, who connected it, and the scopes. Disconnect lives in the same row.
5. To edit issues yourself, connect your own account under Your connections, like any member. The org grant is read-only for everyone, you included.

The org grant is optional. Without it, members who have not connected their own account see a connect screen in the panel instead of issues, and nothing else changes.

Connect your own account (members)

1. Open any Linear notification email in Gmail with the OrgOrg extension installed, and open the OrgOrg panel from the right rail.
2. Click Connect Linear. Linear opens in a new tab. Pick your workspace and allow the permissions.
3. The tab ends on "Connected. Back to Gmail." The panel in Gmail fills in on its own, with no reload.

The same connection is available from Your connections, next to your Google and Slack grants, and that is where you disconnect it.

Which emails open the panel

• Notifications from notifications@linear.app: the single-issue mails and the "N unread notifications" digests. The panel shows up to ten of the issues the email links, newest first.
• Extension 2.6.33 or later: the sidebar opens by itself for a Linear notification, and the panel shows the exact issues. Earlier builds do not capture Linear links, so the panel shows your unread Linear inbox instead, once you open it from the rail.

Permissions, in plain language

OrgOrg asks Linear for three scopes, the same for the personal and the org grant:

• Read: the issues an email names, their team's workflow states, and the active members, so the panel can offer them in the state and assignee controls.
• Write: change an issue's state and assignee. Used only through a personal grant, and only when you change a control in the panel.
• Create comments: post the comment you write in the panel. Used only through a personal grant.

OrgOrg does not ask to create issues, to read your inbox settings, or to administer the workspace.

What OrgOrg stores

• The grant itself: Linear's access token, which expires after one day, and the refresh token that renews it. Disconnecting deletes the grant from OrgOrg and asks Linear to revoke the token.
• A per-person snapshot of each issue the panel showed: identifier, title, link, state, assignee, priority, and the team's state and member lists. Snapshots are private to the person who read them and are deleted with their profile.
• Nothing from the issue description or the comment bodies. The panel links to Linear for those.

Linear rate limits each account's API use per hour. The panel reads at most ten issues in one request and never more than once every fifteen seconds per issue, so ordinary use stays far below the limit. When Linear does throttle, the panel keeps the last read on screen and says so.

Troubleshooting

• "Connect Linear to see these issues": nobody has connected Linear for you. Click Connect Linear, or ask an administrator to connect the org grant.
• "Read through your org's Linear connection": you are reading through the org grant. Connect your own account to edit.
• "Linear stopped accepting your token": the grant was revoked in Linear or its renewal failed. Reconnect from the panel or from Your connections. For the org grant, an administrator reconnects it from the Linear row on the connectors page.
• "Not visible with your Linear account": the issue lives in a team or a workspace your grant cannot see. Open it in Linear, or connect the account that can.
• The panel shows your inbox, not the issues in the email: your extension is older than 2.6.33 and does not capture Linear links. Update the extension from the Chrome Web Store.
• "Linear did not answer": a network or Linear error. Click Refresh at the bottom of the panel.

Related

The browser extension guide covers the Gmail panel itself, and the Gmail add-on guide covers the phone fallback, which does not show Linear issues.