Source: https://docs.pageloop.ai/guides/linear-integration

# Linear integration

# Linear integration

Connect Linear to use product work as evidence for documentation. Pageloop can research issues you name in a documentation request and run scheduled checks for completed work that affects your readers.

The connection supplies source material, not a publishing destination. [Connect a knowledge base](/guides/connect-knowledge-base) so Pageloop can compare issues with existing articles and draft changes for review.

## Before you begin

- Sign in to Pageloop as an **Admin**. Editors and Contributors can view integrations but cannot configure them.
- Use a Linear account that can authorize the Pageloop app for the intended workspace and teams. Follow any app-approval requirements in your Linear workspace.
- Choose the team that owns the product work you want to monitor. Each connection supports one team.

## Connect and configure Linear

1. Open **Integrations** from the sidebar, or **Settings → Integrations**.

2. Find **Linear** under **Project management** and select **Connect**. You can use **Search integrations** to find the card.

   ![Linear card under Project management with Connect outlined](/images/uploads/uploaded-image-0-cccd90e3.png)

3. Review Linear's requested permissions and authorize the app for the intended workspace and accessible teams.

4. Back in Pageloop, **Connecting Integration** appears, followed by the **Integration connected** toast. **Configure Linear** opens automatically until a team is saved. The dialog says “Select the Linear team and project to integrate with.”

5. Under **Select a team to sync issues from**, search for and choose one team. Private teams show a lock; public teams show a globe.

   ![Configure Linear with the team picker open, showing search and public and private team icons](/images/uploads/uploaded-image-1-1b27a92a.png)

6. Check the team's description below the selection. The dialog also has an optional project field.

   ![Configure Linear with a selected team, its description, and Save Configuration outlined](/images/uploads/uploaded-image-2-05d58f47.png)

7. Select **Save Configuration** and check for **Configuration saved**, with “Successfully configured Linear team: `<your team>`”.

8. Check that the card reads **Connected**. Select the gear button (**Configure**) to reopen the dialog and verify the saved team.

![Linear card reading Connected with the Configure gear outlined](/images/uploads/uploaded-image-3-8770c728.png)

Until you save a team, the card shows **Finish setup**. Select it to reopen **Configure Linear**. A connection without a saved team is not watched.

## Permissions and what Pageloop can read

The Linear authorization requests `read`, `write`, `app:assignable`, and `app:mentionable` access as an app. The read permission supports research; the other permissions let the app participate in Linear's mention and delegation surfaces. This is not a read-only installation, even though the documentation agent's research queries are read-only.

Pageloop can search issue titles and descriptions and retrieve issue identifiers, titles, descriptions, states, URLs, and update times. Its read-only queries can inspect additional accessible issue context, such as comments, labels, teams, and projects, when relevant to the task. The information available depends on the access granted to the Linear app.

> [!WARNING]
>
> The saved team defines what Pageloop should monitor; it is not a hard permission boundary for all research. The agent's Linear search and read-only query tools can reach other data available to the connected app. Scheduled workflow guidance tells the agent to ignore issues from other teams. Restrict the app's authorization in Linear when you need an access boundary, and name the intended team in your workflow steps.

The documentation agent does not use its research tools to edit Linear issues or run GraphQL mutations. Mention and delegation replies do write a comment to the Linear issue, as described below. Do not treat the integration as a general-purpose issue-management or two-way documentation-sync tool.

## Supported workflows

### Research named issues

In a documentation request, give Pageloop the Linear issue identifier or link and explain the result you want. For example: “Use these completed export issues to update the export guide. Verify permissions and limits, and leave unrelated pages unchanged.”

Pageloop reads the available evidence, checks existing documentation, and proposes supported changes. An issue link helps identify the work; it does not grant access beyond the connected app's permissions.

### Check completed work on a schedule

For Pageloop-hosted knowledge bases, saving the integration configuration creates a draft workflow named **Keep docs in sync with Linear** in **Workflows**. Open it there to activate or edit it. The draft's schedule is daily at **09:00** in your time zone; once activated, it runs daily until you change its schedule. Write steps that name the team and which changes matter to your readers. See [Create and manage workflows](/guides/workflows) for the full setup, test, and activation process.

Scheduled Linear checks use completed issues as documentation candidates and skip backlog, in-progress, and cancelled work. A completed issue does not mean an article must change: Pageloop compares the evidence with existing coverage and can leave the documentation unchanged.

Checks are periodic, not an immediate trigger for every issue update. Scheduled checks follow the saved team and start only when that team's issues have changed since the last run. Otherwise, the result is “Nothing new since the last run”.

### Mention or delegate to Pageloop

The integration receives Linear agent sessions created when the Pageloop agent is mentioned or delegated an issue. The issue and any initiating comment provide the context for a suggestion request. This is a direct request, separate from a scheduled check of completed issues.

Pageloop reacts in the agent session with 👀 and posts a comment on the issue. The comment lists articles it suggests adding or updating and says “Review them on Pageloop.” If no documentation changes are needed, the comment says that no documentation updates were needed.

## What happens after research

Supported documentation changes appear in Pageloop for review, with source references where available. Related issues can support one proposal, and a run can determine that no edit is needed. If the evidence leaves an important detail unresolved, the run can ask for input instead of inventing it.

Review the proposed wording and supporting issues before publishing. Connecting Linear and running a workflow do not publish documentation automatically.

## Disconnect Linear

1. Point at **Connected** on the Linear card; it changes to **Disconnect**. Select it.
2. Review **Disconnect Linear?**.
3. Select **Disconnect** to confirm, or **Keep connected** to cancel.

![Disconnect Linear? dialog with Disconnect outlined](/images/uploads/uploaded-image-4-b78e6f52.png)

The **Linear disconnected** toast confirms that Pageloop's access to Linear is revoked. The draft workflow stays. Runs fail with “Linear is disconnected” until you reconnect; see [Limitations and troubleshooting](#limitations-and-troubleshooting) for the workflow's failure and pause behavior.

## Reconnect Linear

When Linear stops accepting Pageloop's access, the card shows **Needs reconnecting** and “Linear needs to be reconnected. Pageloop lost access, so it is paused until you reconnect it.” Select **Reconnect Linear** and approve access again.

## Limitations and troubleshooting

Pageloop can make up to **10 Linear queries per run**.

| Symptom                                                                                                                        | What to check                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Save Configuration** is disabled.                                                                                            | Wait for the teams to load and select a team. A project selection is optional.                                                                                                                                                                               |
| The intended team is missing or inaccessible.                                                                                  | Check which workspace and teams were authorized in Linear. Pageloop can only use teams the app can access.                                                                                                                                                   |
| **Error loading teams**, with “Failed to load Linear teams”.                                                                   | Teams did not load. If the message says “Linear authentication failed. Please reconnect your Linear integration.”, reconnect Linear.                                                                                                                         |
| **Configuration failed**, with “Team not found or not accessible”.                                                             | The app cannot see that team. Check the authorized workspace and teams in Linear.                                                                                                                                                                            |
| **Error connecting integration**, with “Failed to exchange code for tokens” or “Failed to fetch Linear workspace information”. | Start again from **Connect**.                                                                                                                                                                                                                                |
| Linear is shown as **Not connected** in a workflow despite authorization.                                                      | Finish the team configuration in Integrations. Workflows need a connected source that has been told what to watch.                                                                                                                                           |
| A run fails with “Linear is disconnected”.                                                                                     | The workflow shows “The source is disconnected - reconnect it in Integrations”. Restore the Linear connection in Integrations and retry the documentation work. Three failures in a row pause the workflow.                                                  |
| A run says Linear is unavailable.                                                                                              | Ask an Admin to check and restore the Linear connection. A refused token refresh disables Linear reads for the rest of that run; repeating the same lookup in that run will not repair authorization. Retry the documentation work after access is restored. |
| A large request is only partly researched.                                                                                     | Research queries have per-run complexity and query limits. Narrow the issue list, team, project, or period. A partial result is not proof that other issues contain no relevant work.                                                                        |
| No suggestions appear.                                                                                                         | Check the saved team, active workflow, schedule, and run history. Confirm that relevant work is completed and not already documented.                                                                                                                        |

## Related guides

- [GitHub integration](/guides/github-integration)
- [Jira integration](/guides/jira-integration)
- [Slack integration](/guides/slack-integration)
- [Where Inbox items come from](/guides/where-inbox-items-come-from)
- [Review an Inbox item](/guides/review-inbox-item)
