Connect Linear
Link issues and projects to a design doc, review execution status and confirm issue proposals from a finished plan.
Early access. Email hello@archdocs.io to turn it on for your organization.
Connect Linear when you want issues and projects beside the design they implement. The integration requires Business or Enterprise. Linear owns execution; its state never changes design doc state.
Connect a workspace
- Open Organization Settings > Integrations > Linear.
- Start the connection and complete OAuth as a Linear workspace administrator. Installation uses an app actor and requires workspace admin approval.
- Return to ArchDocs and check the connected workspace.
Connecting, disconnecting and resyncing require integrations:manage. The OAuth request uses read, write and issues:create scopes with PKCE S256. Each ArchDocs organization connects to one Linear workspace, and a workspace connects to only one ArchDocs organization.
Link issues and projects
On a design doc, find Work in Linear and paste an existing issue or project into the add input. Linking and unlinking require docs:write; reading requires docs:read and access to the design doc.
| Reference | Accepted form |
|---|---|
| Issue | An identifier such as ENG-12, an issue UUID, or https://linear.app/workspace/issue/ENG-12/optional-title. |
| Project | https://linear.app/workspace/project/project-name-slugId, including /overview. Project resolution also accepts UUIDs and numeric slug IDs. |
The card shows issue states and assignees. Linked projects show status and progress, with a lead and target date when available. Completed projects say Completed in Linear. Shared design docs can receive backlinks in Linear that show the design doc number, title, status and space. Those cards do not expose variation text, briefs or questions. Moving a doc to My docs removes its backlinks while retaining the ArchDocs links.
Private teams are never shown, linked or counted. Unknown visibility is restricted too. Projects appear only when at least one associated team is explicitly public. ArchDocs does not check each reader's personal Linear access, so it limits these views to public teams.
You can also put issue cards on architecture diagrams by pasting a Linear issue URL. These cards keep execution context beside the diagram.
Propose issues from a finished plan
On the Implementation plan, select Propose Linear issues, or use propose_linear_issues over MCP. The design doc must be in a space, active and unshipped. Its Implementation plan must be Approved when approvals are on, or Ready when approvals are off, with no open amendment.
The draft uses the plan's Markdown task list or supplied items. Checked tasks and duplicate titles are excluded. If no team is supplied, ArchDocs chooses the only public team; if several exist, choose one. A project must already be linked, public and active.
A person reviews titles, descriptions, teams, projects and excluded tasks, then confirms the draft in ArchDocs. Agents can propose; agents never confirm or retry issue creation. Confirmation checks that the pinned plan and reviewed draft still match. If the plan changes, review a fresh proposal.
Compare issues with pull requests
Work in Linear correlates the design doc's linked GitHub PRs with issues. It uses Linear GitHub attachments first and an issue identifier in the PR title as a fallback. Attached PRs not linked to the doc can appear as hints for you to review.
Correlation records execution context. It does not add verification evidence, alter plan versus actual or change shipping eligibility. Connector facts keep their source and scope. A merged PR, a passing check, a closed issue and a correct deployment are different facts. Done in Linear never approves, ships or verifies a design doc.
Disconnect
Use Disconnect in the Linear settings page. ArchDocs attempts token revocation, clears stored tokens and hides retained cached issues and links. Reconnecting the same workspace restores those links; connecting a different workspace removes the previous workspace's cached issues and links. Resync refreshes tracked records and does not discover historical untracked links.