Linear connector

Connect a Linear workspace, review its Git-backed scope, and keep selected work context available to ctx|.

The Linear connector mirrors selected workspace context into a GitHub repository, then sends that repository through the normal ctx| ingestion pipeline. The generated linear/config.yaml pull request makes the scope reviewable before content sync begins.

ctx| requests read-only Linear access. It does not create or update Linear issues.

Fully managed app flow

The hosted ctx| service supplies the Linear OAuth application and webhook configuration. Self-hosted operators must register their own application before authorization can succeed. See Self-host Linear.

What is mirrored

You can select teams, projects, documents, and initiatives. Their related content can include:

Issues and native Linear comments.
Project and initiative updates.
Cycles, labels, and referenced users.
Customer requests when their parent scope is selected.
Linear attachments and explicit embedded external media copied into git with relative links.

GitHub pull requests, commits, reviews, diffs, CI output, and patches are not copied through Linear. When Linear references GitHub work, ctx| stores only reference metadata and the original URL. This avoids duplicating source content that the GitHub connector already indexes.

Customer request privacy

Customer requests can contain external names, feedback, or support context. Review the selected scope and the generated pull request before merging it. Repository access becomes the practical access boundary for the mirrored files.

Prerequisites

Permission to authorize an application in the Linear workspace.
A ctx| GitHub connection with access to the destination repository.
Permission to merge the generated configuration pull request.

Configuration source of truth

Linear scope exists only in linear/config.yaml:

Draft scope is the YAML on the generated configuration pull request's branch.
Live scope is the YAML on the selected target branch after that pull request is merged.

ctx| does not keep a second draft or live scope outside Git. The connection tracks where content belongs and whether setup is complete; the merged YAML remains the source of truth for what Linear content is approved.

Setup flow

Connect Linear

Open Connectors, choose Add connection, then select Linear. Authorize the read-only ctx| application in the Linear popup.

Confirm GitHub

Linear content is stored in Git before ingestion. If GitHub is not connected for this ctx| organization, complete the GitHub App installation first.

Choose a context repository

Select an existing connected repository. A dedicated private repository usually gives the clearest ownership and access boundary; create it in GitHub first, grant the ctx| GitHub App access, then refresh the repository list in ctx|.

Select scope

Select at least one team, project, document, or initiative. Team selection provides broad coverage; selecting individual projects or documents keeps the mirror narrower.

Merge the configuration pull request

ctx| opens a pull request containing linear/config.yaml. Review the workspace ID, selected scope, and repository audience, then merge it.

The pull request branch YAML is the draft. The target branch YAML becomes live only after merge; the setup dialog submits scope to that Git workflow rather than storing another copy.

Wait for initial sync and ingestion

After GitHub reports the merge, ctx| performs the first Linear mirror and starts repository ingestion. The connector reaches Connected when the mirror succeeds. Repository indexing may continue afterwards; see Ingestion for the indexing lifecycle.

Files in the repository

Mirrored files live under linear/, grouped into stable paths such as teams/, projects/, issues/, documents/, initiatives/, cycles/, labels/, users/, and customer-requests/. Paths include stable Linear IDs, so renaming an issue or project does not create a second copy.

Linear file uploads and explicit embedded media live in a sibling <entity>/assets/ directory beside the entity's Markdown file. Ordinary link-only attachments remain links and are never crawled. Each asset is capped at 25 MiB and each entity has a 100 MiB asset budget. Unsafe, unavailable, or oversized downloads leave a Linear link or textual stub. GitHub pull requests and commits remain references rather than copied attachments.

Do not hand-edit generated content. Change scope through Manage scope and review the replacement configuration pull request.

Keeping content current

Linear sends signed webhook events to ctx| when supported entities change. While the connector is live, ctx| validates the event against the Git scope, updates the affected files, and starts another repository ingestion. Events that arrive before the connector is live, including during initial sync, are skipped rather than queued for later. Missed webhook events are not automatically backfilled: repair webhook delivery, then update the affected entities in Linear again so fresh events are delivered, or use Retry content sync after a failed initial mirror.

Verify the complete flow

Complete Linear OAuth and confirm the expected workspace appears.
Select a connected GitHub repository and at least one scope item.
Open and merge the generated linear/config.yaml pull request.
Confirm the connector reaches Connected and the repository contains generated files under linear/.
Edit a mirrored issue in Linear and confirm the matching Git file changes.
Confirm the destination repository reaches an indexed state in ctx|.

Steps 3 and 4 test the GitHub push webhook and initial mirror. Step 5 separately tests Linear webhook delivery.

Troubleshooting

Authorization fails

Allow popups and retry. On fully managed ctx|, report persistent OAuth errors to support. On a self-hosted deployment, ask the operator to verify that Linear OAuth credentials are configured and that the callback URI matches exactly.

No pull request appears

Confirm that at least one scope item is selected and that the GitHub App has write access to the destination repository. Empty repositories are supported; ctx| initializes the default branch before opening the pull request. If setup reports that pull request creation failed, open the connector and choose Retry configuration pull request.

The connector stays on “Approve configuration”

The configuration pull request must be merged, not merely approved. Confirm that linear/config.yaml reached the default branch and that GitHub webhooks for the ctx| GitHub App are healthy.

Content sync failed

Open the connector and choose Retry content sync. This retries the mirror without opening another configuration pull request. If it fails again, ask the operator to check worker logs, Linear token refresh, GitHub write access, and outbound access to api.linear.app.

Changes in Linear do not arrive

Initial sync can still succeed when webhooks are misconfigured. Ask the operator to verify the Linear application webhook URL and signing secret. See Self-host Linear for the exact settings.

Linear authorization was revoked

Open the connector and authorize Linear again. Incremental updates stop while the workspace authorization is revoked.

Removing the connector

Removing the connector deletes its ctx| authorization and repository binding from the connection record. It does not delete linear/config.yaml, generated files, or Git history from the destination repository; remove those in GitHub if they are no longer required.

On this page