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 authorisation 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.
Attachment metadata and 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 in PostgreSQL. The Linear connection's connections.config stores only the repository binding and setup state, including the repository, target branch, enabled state, and pending configuration pull request metadata.

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.

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, directly enqueues an OpenWorkflow entity-sync run, updates the affected files, and starts another repository ingestion. Events that arrive before the connector is live (including during initial sync) are skipped — the same trade-off as Confluence — rather than buffered in a Linear-specific dirty-entity table. 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 content retry / remirror after a failed initial sync.

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