Connect Linear
Connect Linear with read-only access, see which teams and items Gurusup reads, bring in past work, and reconnect if the app is removed.
Admins only. Besides issues and projects, Gurusup learns from initiatives, customer requests and releases, and it never changes anything in Linear.
At a glance
| Topic | Details |
|---|---|
| Who can connect | Admins |
| What you need | A Linear workspace admin to approve the app |
| What Gurusup reads | Public issues, projects, initiatives, documents, cycles, releases, release notes and customers |
| How changes arrive | On every change, through the app's webhook |
| Past content | Import history, up to the last year |
| Knowledge access | Default access, Restricted or Private. See Who can read it. |
Before you start
- Find a Linear workspace admin to approve the app. Gurusup is installed for the whole Linear workspace, not for the person who clicks, so it keeps working if that person leaves.
- The same Linear workspace can be connected to several Gurusup organizations, each approving it on its own. Your organization takes one connection per Linear workspace.
Connect Linear
Open the Linear connector
In the sidebar, open Sources, then Catalog, find Linear (use Search sources if you need to) and click Connect on its row. Its page opens. Next to Organization accounts, click Connect for the organization. The dialog Connect Linear for the organization opens.
Choose who can read it
In the dialog, under Who can read it, keep Default access, or choose Restricted or Private from Access mode and pick the people.
Connect and approve
In the dialog, click Connect. Gurusup says "Opening authorization for Linear." and sends you to Linear. Approve read access for your workspace. Linear sends you back, and a message says Linear is connected.
The approval link lasts 15 minutes. If you take longer, start again from the Linear page in Catalog. Linear asks for read-only access, which includes reading customers and initiatives.
What Gurusup reads
Gurusup reads the public teams of your Linear workspace. Private teams stay out. The Linear page does not list the teams.
| Item | What a document holds | Comes in when |
|---|---|---|
| Issues | Identifier and title, team, status, priority, assignee, creator, project, labels, due date, description, attachments as links, and comments with their authors | The issue's team is public |
| Projects | Status, lead, health, teams, start and target dates, description, content and project updates | Every team on the project is public |
| Initiatives | Status, owner, health, target date, description, content, initiative updates and their public projects | The initiative is public |
| Documents | Title, where it belongs, author and content | The issue, project, initiative or team it belongs to is public |
| Cycles | Team, dates, description and the issues in the cycle | The cycle's team is public |
| Releases | Version, stage, pipeline, dates, description, public issues and release note titles | Every team on its release pipeline is public |
| Release notes | Title, releases and content | Same as releases |
| Customers | Status, tier, owner, domains, revenue, size, and requests linked to a public issue or project | The customer is not archived |
Each item links back to Linear.
What Gurusup does not read
- Private teams, and anything private in Linear.
- Projects that include a private team, and documents that belong to something private.
- Customer requests linked only to private work.
- The contents of attachments. Gurusup keeps their title and link.
How changes arrive
| Change in Linear | What Gurusup does |
|---|---|
| An item changes | Reads it again |
| A comment, attachment or update is added | Reads its issue, project or initiative again |
| Linear moves an issue to the next cycle, reorders issues or completes a cycle on its own | Nothing. Only changes someone makes count: an edited cycle (name, description or dates) or an issue with more changed than its cycle or order. |
| An item is deleted, archived, moved to trash or stops being public | Withdraws it. What Gurusup learned only from that item goes; what other sources also back stays. |
When you connect, only new changes come in. The History section says "Only new content comes in until you import past content." Follow each item on Follow ingestion.
Import past work
Open Import history
On Sources, open the Linear page. Under History, click Import history.
Pick how far back
Pick Last week, Last month, Last 3 months, Last 6 months or Last year. Gurusup counts what changed, for example "~120 issues, 500+ documents", and shows what the import would use out of what you have left this month, in euros.
Import
Click Import. When it finishes, the row reads, for example, "Imported the last month".
A window you already imported shows "Already imported", and you can always pick a longer one. What happens when the import costs more than you have left, or stops, is in Import history.
Who can read it
What Gurusup learns from Linear is one source, and its access covers every item.
| Knowledge access | Who reads it in Brain |
|---|---|
| Default access | Everyone, according to what they are already allowed to see: admins every category, members and agent accounts the categories an admin granted them. |
| Restricted | Only the people you pick. Administrators are not included unless you pick them. |
| Private | Only you. Administrators are not included. |
Set it under Who can read it before you connect, and it applies before Gurusup reads anything. To change it later, open the Linear page and change Access mode under Knowledge access; it saves as soon as you change it. Restricting later only covers what arrives after that. See Restrict a source to specific people.
Check that it worked
Check the badge
On Sources, open the Linear page. Under Organization accounts, the badge reads Connected.
Comment on an issue
Comment on an issue in a public team.
Follow it
Open Ingest and pick the Linear source in the filter. The issue moves to Learned.
Reconnect
If the app is removed in Linear, or Linear stops accepting Gurusup's access, the connection shows Needs reconnect. Click Reconnect on the account's row under Organization accounts and approve again. Until you do, Gurusup reads no new changes. Your knowledge access and what Gurusup learned stay.
Disconnect
On Sources, open the Linear page. Under Danger zone, open the menu on Disconnect, choose Disconnect and confirm. Gurusup deletes the credentials it stored for your organization, and what it learned stays. Gurusup does not revoke the approval in Linear: to remove the Gurusup app from the workspace, do it in Linear, which also cuts off any other organization that connected the same workspace. See Remove, disconnect and what stays.
If it does not work
When you come back from Linear:
| Message | What to do |
|---|---|
| "Access to Linear wasn't granted, so nothing was connected. Start again when you're ready." | Start again and approve. |
| "The connection to Linear didn't finish, so nothing was connected. Start connecting it again." | Start again from the Linear page. |
| "OAuth state expired. Start the connection again." | The approval link lasts 15 minutes. Start again. |
| "This connection request was not found or was already used. Start the connection again." | Start again from the Linear page. |
| "We couldn't match this Linear sign-in to a connection request. Start connecting Linear again." | Start again from the Linear page. |
| "We couldn't connect Linear because of a problem on our side. Nothing was connected. Try again in a few minutes, and contact support if it keeps failing." | Try again later. Contact support if it keeps happening. |
On the Linear page:
| Message | What to do |
|---|---|
| "Could not disconnect. We couldn't disconnect Linear just now. Nothing was removed. Try again in a few minutes, and contact support if it keeps failing." | Try again later. |
| "The import didn't finish. Try again, and contact support if it keeps failing." | Click Try again. If it keeps failing, contact support. |
| Items stop arriving | What to do |
|---|---|
| The badge reads Needs reconnect | See Reconnect. |
| A team is private | Private teams stay out, and so does a project that includes one. |
| The item is older than the connection | Use Import history. |
| Ingestion paused, Demo Mode, or the item Paused on Ingest | While ingestion is paused or Demo Mode is on, Gurusup ignores changes from Linear. See Connector troubleshooting. |
Still stuck? Contact support with the item's identifier and when it changed.