# Jira and Linear: link issues to proposals and docs

Source: https://versodocs.com/docs/issue-links

Show which issues a proposal implements and which issues a spec answers. Paste the issue URL in **Linked issues**: it works with no setup. When an admin connects Jira or Linear, VersoDocs shows each issue's title and status and comments on it when the proposal is published. Team plan and up. (Team+)

## Plans

|   | Free | Team | Pro |
| --- | --- | --- | --- |
| Jira + Linear issue links | — | ✓ | ✓ |

## Link an issue

- **On a proposal:** the **Linked issues** button in the right column. Anyone who can open the proposal can link issues.
- **On a document:** the link icon in the document header. Editors can link and unlink.
- Paste `https://<site>.atlassian.net/browse/KEY-1` (board and issue-view URLs work too) or `https://linear.app/<team>/issue/KEY-1`.
- Up to 20 issues per proposal or document.

## Connect Jira or Linear (optional)

Org admins, in **Settings → Integrations → Jira & Linear**: **Connect Jira** (Atlassian sign-in, pick the Jira Cloud site) or **Connect Linear**. Then new links show title and status, and when a linked proposal is published VersoDocs comments on up to 5 linked issues (the proposal's, then the document's) with a link to the new Current version. Disconnecting keeps the links.

Permissions asked: Jira `read:jira-work`, `write:jira-work` (comments), `offline_access`; Linear `read`, `comments:create`. Tokens are stored encrypted.

## API and MCP

| Action | REST | MCP | Scope |
| --- | --- | --- | --- |
| List a proposal’s issues | `GET proposals/{id}/issue-links` | `list_links` | `proposals:review` |
| Link to a proposal | `POST proposals/{id}/issue-links` | `link_issue` | `proposals:review` |
| List a document’s issues | `GET docs/{id}/issue-links` | `list_links` | `docs:read` |
| Link to a document | `POST docs/{id}/issue-links` | `link_issue` | `docs:write` (Pro for API keys) |