EvalSuite for Linear: Connect, Use, and Remove

Before you start

EvalSuite keeps the coaching loop and canonical action-item history inside EvalSuite. Linear is the linked execution system for teams that already run work there.

The shipped sync is org-scoped and limited to persisted action items. Accepted AI follow-up drafts only become issue-eligible after they are saved into `action_items`.

• EvalSuite syncs title, generated EvalSuite context body, assignee, due date, and open/completed state.
• Ticket creation is always explicit. EvalSuite does not silently export drafts or private notes into Linear.
• Remote delete never deletes the EvalSuite action item. The link moves to `Needs attention` instead.
• If an action-item owner has no Linear member mapping, the Linear issue is created or updated unassigned and the link shows `Needs mapping`.

Connect the app

Use the connection flow when your workspace is ready to authorize EvalSuite against one Linear workspace.

1. Open `Settings -> Integrations -> Linear` in EvalSuite.
2. Click `Connect Linear`.
3. Complete the Linear OAuth flow for the workspace you want EvalSuite to use.
4. Return to EvalSuite and confirm the workspace connection shows as `Connected`.

Configure org destinations

Destinations tell EvalSuite which Linear team and workflow states to use for newly created issues.

1. In `Settings -> Integrations -> Linear`, open the `Destinations` section.
2. Choose the Linear team that should receive EvalSuite action items.
3. Choose the default open state for newly created issues.
4. Choose the reopen state EvalSuite should use when a completed action item is reopened locally.
5. Save the done state IDs that EvalSuite should treat as completed for this team.

Configure member mappings

Member mappings link EvalSuite `profiles.id` to Linear users so assignee sync stays deterministic.

1. Click `Auto-match by email` first. EvalSuite checks active org members against Linear users and saves exact matches.
2. Review the saved mappings list.
3. Use the manual mapping form if the Linear email does not match the EvalSuite member email.

Create a Linear issue from an action item

Use this when the commitment is already real and you want the work represented in Linear immediately.

1. Open the action item in EvalSuite.
2. Click `Create` in the Linear controls.
3. EvalSuite creates the Linear issue in the default Linear destination, stores the durable link, and adds an EvalSuite backlink attachment.

Link an existing Linear issue

Use this when the work already exists in Linear and you want EvalSuite to stay aligned with it.

1. Open the action item in EvalSuite.
2. Click `Link existing` in the Linear controls.
3. Paste a Linear issue identifier or Linear issue URL.
4. Confirm the link. EvalSuite fetches the remote issue and stores the durable Linear link.

Understand sync behavior and conflict handling

EvalSuite and Linear use field-level last-writer-wins by `updated_at` timestamp for supported fields.

• Remote reopen always wins. If the Linear issue moves back to an open state, EvalSuite clears `completed_at` and the action item reappears in carry-forward.
• Remote done marks the EvalSuite action item complete when Linear closes the issue and EvalSuite is still open.
• If both sides edit the title in the same sync window, the newer timestamp wins and overwrites the older value.
• Remote due-date removal clears the local due date when Linear is newer.
• Remote archive or delete never deletes the EvalSuite action item. The link moves to `Needs attention` for manual repair.

Troubleshooting

Use Support when the Linear connection is blocked, token refresh fails, or the workspace needs manual diagnosis.

• `Needs mapping` means the local owner or remote assignee is not fully mapped yet.
• `Needs attention` means the Linear issue was removed, archived, or otherwise stopped behaving like a durable sync target.
• `Paused` usually means the Linear token was revoked or the provider was disabled for the workspace.
• `Queued syncs` in the Linear settings card means EvalSuite has replayable work waiting for the next usable Linear connection.

Remove access cleanly

Use this when your workspace no longer wants Linear-backed action-item sync.

• Existing EvalSuite action items remain in EvalSuite after removal.
• Linked Linear rows move to `Paused` or `Needs attention` based on the last known state. EvalSuite does not delete historical coaching artifacts.

1. Open `Settings -> Integrations -> Linear` in EvalSuite.
2. Click `Remove`.
3. Confirm the connection is no longer active.

Sources and verification basis

• Linear OAuth 2.0 authentication
• Linear webhooks
• Linear GraphQL API

Need Linear setup help?

Use Support if Linear authorization, destination setup, or member mappings need manual verification before your workspace can rely on synced action items.

Open Support · Create workspace