Skip to content

LINEAR.md

Latest commit

 

History

History
241 lines (169 loc) · 11 KB

LINEAR.md

File metadata and controls

241 lines (169 loc) · 11 KB
Raw

Linear Integration

Open-Inspect's Linear integration starts coding sessions from Linear issues. Mention or assign the Linear Agent to start work, then use Linear for progress, results, and follow-ups.

This guide is for people using the Linear integration day to day. If you are installing the Linear OAuth app or deploying the worker, start with the Linear Bot setup guide.

Quick Start

  1. Open the Linear issue you want Open-Inspect to work on.
  2. Mention the agent in a comment: 
    @OpenInspect please implement this issue and open a pull request
  3. Or assign the issue to the Linear Agent when the issue already explains the work.
  4. Include owner/repo if the issue could match more than one repository.
  5. Use View Session to watch the full session.
  6. Send follow-ups through the same active Linear Agent session.

What Linear Can Do

Workflow How it works
Start from an issue mention Mention the Linear Agent on an issue
Start from assignment Assign the issue to the Linear Agent
Continue active work Send a follow-up through the same active Linear Agent session
Stop or cancel work Stop or cancel the Linear Agent session to stop the Open-Inspect session
Resolve the repository Let Open-Inspect infer the repo, or include owner/repo when asked
Follow progress Watch Linear activities or open the full session with View Session

Start work by mentioning or assigning the Linear Agent. Regular issue comments only continue work when they are part of an active Linear Agent session.

Start, Continue, or Stop Work

From an @mention

Mention the Linear Agent on an issue when you want Open-Inspect to start work from that issue:

@OpenInspect can you fix the failing invite flow described above?

Open-Inspect uses the issue and recent comments as context. The triggering comment becomes the agent instruction, so include the concrete work you want done.

From Assignment

Assign the issue to the Linear Agent when the title and description already describe the work.

Assignment works best when the issue includes:

  • A clear title and description
  • Acceptance criteria or expected result
  • The target repository, if it is ambiguous
  • Whether the agent should open a pull request

Follow-Up Messages

Follow-up prompts on an issue with an active Open-Inspect session go to that session. When available, Open-Inspect adds recent agent output as context.

Issue-to-session mappings are kept for several days. If the mapping has expired, or if the previous session was stopped or cancelled, a new Linear Agent request may start a new Open-Inspect session.

Stop or Cancel

Stopping or cancelling the Linear Agent session stops the associated Open-Inspect sandbox session and clears the issue's session mapping.

Repository Selection

Before starting work, Open-Inspect chooses a repo from the Linear project, team, labels, issue text, comments, and repo metadata.

If the issue could match more than one repository, include the intended repository name in the issue or trigger comment:

Please handle this in acme/billing-api.

If Open-Inspect asks for clarification, reply with owner/repo. That answer is used on the next resolution attempt.

Admins can map Linear projects or teams to repositories. See Configure Repo Mapping for details.

If the resolved repo is outside the selected Linear scope, Linear shows an error and no session starts.

What Linear Shows

Activity What it means
Thinking Open-Inspect is analyzing the issue or choosing a repo
Working A session has started
Tool progress Optional updates for file reads, edits, and commands
Clarification Open-Inspect needs more information, usually the repo name
Completion or error The session finished, failed, or could not continue

When a session starts, Linear receives a View Session link. If the agent opens a pull request, Linear receives a Pull Request link when the session finishes.

Open the web session for live output, logs, artifacts, and file changes. For a human-initiated session, Open-Inspect moves an unstarted issue to the team's lowest-position started workflow state only after the initial prompt reaches a live sandbox. It leaves automation-initiated, already-started, completed, and canceled issues unchanged. Follow-up prompts do not change issue status.

Open-Inspect does not update labels, assignee, priority, or project. Pull-request workflow changes remain the responsibility of Linear's GitHub integration and the team's PR automation settings.

Settings

Open the web app and go to Settings > Integrations > Linear to configure the Linear Agent.

Setting What it controls
Default model and effort Model and reasoning depth for Linear-started sessions
Repository Scope Whether Linear can run in all accessible repos or selected repos
Issue Session Instructions Extra guidance appended to Linear issue prompts
Allow user model preferences Whether admin-managed user preferences can override the model
Allow model labels (model:*) Whether Linear issue labels can choose the model
Tool progress activities Whether Linear shows intermediate file and command activity
Repository Overrides Per-repository defaults for model, reasoning, and Linear behavior

If no Linear settings are configured, all accessible repositories are in scope, user preferences and model labels are allowed, and tool progress is enabled.

Model selection uses this priority, highest to lowest:

  1. model:* issue label, when allowed.
  2. Linear user preference, when allowed.
  3. Repository override or global Linear default.
  4. Deployment default model.

Linear user preferences are currently admin/API-managed, not set from a self-service Linear screen.

Admin and Safety Notes

  • Linear webhooks are verified before Open-Inspect acts on them.
  • Linear client credentials, runtime access tokens, webhook secrets, and callback secrets stay server-side. Runtime access tokens are cached and replaced automatically; refresh tokens are not used for runtime API access.
  • Runtime tokens are cached under oauth:client-credentials:{organizationId} with their verified workspace/app identity and expire with the provider lease. Do not edit cached token values manually.
  • Linear does not provide Git credentials. Repository access still comes from the deployment's configured source-control integration, such as the GitHub App installation.
  • Repository scope in Linear settings controls which resolved repositories can receive Linear-started sessions.
  • Linear issue titles, descriptions, comments, and agent prompts may be sent to the coding agent. Do not include secrets.

Troubleshooting

The agent does not appear in Linear

Confirm the Linear OAuth app is installed in the workspace and that the app was installed with the agent scopes required for mentions and assignment. Setup details live in the Linear Bot setup guide.

A request does not start

Make sure the request mentions or assigns the Linear Agent on an issue. Also check that the issue belongs to a repo Open-Inspect can resolve and access.

If the Worker logs a client-credentials failure, confirm Client credentials tokens is enabled for the application in Linear Settings → API → Applications. Existing eligible installations do not need to be uninstalled and reinstalled. A client-credentials viewer-organization mismatch means the application credentials resolve to a different workspace than the incoming webhook and must be corrected before the deployment is eligible.

Open-Inspect asks which repository to use

Reply with owner/repo. To avoid future prompts, add the repo to the issue or ask an admin to map the Linear project or team.

I see progress in Linear but need full logs

Open View Session. Linear shows status and completion activity, while detailed logs, transcripts, artifacts, and file changes live in the Open-Inspect web session.

Linear stays Working after the web session completes

Linear leaves Working only after the bot delivers a terminal response or error activity. If the web session has completed but Linear has not:

  1. Find the Open-Inspect session ID from View Session.
  2. Confirm the Linear bot logged agent_session.followup for the follow-up webhook.
  3. In control-plane logs, find prompt.enqueue for the follow-up message. A healthy Linear prompt has has_callback_context:true; false means completion had no Linear callback destination.
  4. Confirm control-plane prompt.complete, followed by linear-bot callback.complete. If the first exists without the second, inspect callback routing and context. If both exist, inspect delivery_outcome, linear.emit_activity_failed, credential identity failures, and GraphQL errors. Only delivery_outcome:success confirms the terminal activity reached Linear.

A completion that was skipped cannot repair itself later. After deploying a callback-context fix, send another follow-up through the same Linear Agent session to produce a new terminal activity, or start a new Agent session if the issue mapping has expired.

Linear client secret was rotated

Deploy the replacement LINEAR_CLIENT_SECRET promptly. Linear invalidates tokens minted with the old secret; the Worker replaces the cached token after a cache miss, expiry, or HTTP 401 and retries the rejected API request once. A reinstall is not normally required.

The wrong model was used

Check Settings > Integrations > Linear. Repository overrides, user preferences, and model:* labels can affect model selection. Changes apply to new Linear-started sessions.

The wrong repository was used

Check project and team repo mappings, issue labels, repository metadata, and the selected repository scope. If an issue is ambiguous, include the intended owner/repo in the issue or trigger comment.

The agent is active in too many repositories

Limit the source-control installation to intended repositories, or set Repository Scope to Selected repositories in the Linear integration settings.