Connect your Linear workspace to SMP Insights and accessibility findings flow into the same backlog where the rest of your engineering work lives. Click Send to Linear on a finding and you get a fully-formed Linear issue with the tester videos attached. When your team moves the issue through workflow states, SMP shows that progress live next to the original finding.
This guide walks through what the integration does, how to set it up, and what to expect.
What you get
- Send accessibility findings to Linear in one click. Title, description, severity, friction type, WCAG criterion, and cohort travel into the issue body. Tester videos arrive as attachments.
- Issue status syncs back live. Move a finding from Triaged to In Progress to Done in Linear, and SMP Insights shows the new status on the finding within seconds.
- No duplicates. Pushing the same finding twice is a no-op — you get the existing Linear issue back, not a new one.
- Bulk push at engagement end. Send all findings from a project into your backlog with a single confirmation step.
Setting up the connection
1. Open Settings → Integrations
In SMP Insights Portal, click your avatar → Settings → Integrations. You'll see a Linear card with a Connect Linear button.
2. Authorise SMP Insights in Linear
Clicking Connect opens Linear's standard authorisation screen. You'll be asked to grant SMP Insights:
- Read access to your workspace metadata (team names, workflow states, labels) so the picker UI knows what to offer.
- Write access to create issues and attachments.
- Webhook registration so SMP can listen for status changes you make.
Authorising in Linear redirects you back to SMP Insights. You'll see a "Connected" banner and the card will show your workspace name, default team, and the user who connected.
3. Pick your defaults (optional)
The connected card shows two defaults you can edit:
- Default team — which Linear team SMP issues land in. You can override per-push.
- Default starting state — usually Backlog or Triage. Issues are created in this state unless you override.
A more advanced cohort routing option lets you map specific cohorts to specific teams (e.g. blind/low-vision findings to your platform team, cognitive findings to your content team). Not required — leave it empty if a single team handles everything.
Pushing a finding
On any finding page in SMP Insights, click Send to Linear. A modal appears with:
- Team — defaults to your team-of-choice, override here per-push.
- Severity → Priority preview — SMP severities map to Linear priorities like this:
| SMP severity | Linear priority |
|---|---|
| Critical | Urgent |
| High | High |
| Medium | Medium |
| Low | Low |
- Include supporting videos — toggle on (default) to attach each tester video as a separate Linear attachment. Each attachment carries a cohort-branded thumbnail so a stack of five videos visually reads as "five tester perspectives" at a glance. Toggle off to keep the issue lean.
Click Send and the issue is created. You'll see a success toast with the Linear identifier (e.g. ENG-1234) and a deep link. The finding in SMP Insights gets a permanent badge linking back to the issue.
What the issue looks like
The Linear issue body is markdown, structured like this:
> **Severity:** high · **Friction:** navigation · **WCAG:** 1.3.1 · **Cohort:** blind
## Description
When the cookie banner appears, focus is trapped above it. Screen
reader users can't reach the consent button without leaving the page.
## Background
[context about how the finding was identified]
## Our read on it
[the SMP analyst summary]
## Tester voice
> I literally can't find the button.
> — Sam · NVDA
> The page just reads "cookies" forever, there's nowhere to go.
> — Pat · VoiceOver
---
[View in SMP Insights Portal](https://insights.seemeplease.com/...)Attachments appear as a stack of clickable cards beneath the description: one for the insight itself, one for each supporting video. Click any attachment to jump to the tester video at the moment the friction was observed.
Status sync
When anyone on your team changes the issue in Linear, SMP Insights reflects the change within ~5 seconds. The finding in SMP shows a state badge:
| Linear state | SMP badge |
|---|---|
| Backlog | "In Linear backlog · ENG-XX" |
| Todo / Triaged | "Triaged · ENG-XX" |
| In Progress | "In progress · ENG-XX" |
| Done | "Resolved by client · ENG-XX" |
| Cancelled | "Won't fix · ENG-XX" |
The finding's detail page also shows a timeline of every Linear event: state changes, comments, assignee changes, archives. Hover any timeline entry to see who made the change in Linear and when.
Bulk push
On a project's insights summary page, Push all findings to backlog opens a preview table showing:
- One row per insight.
- The team each row will route to (using your defaults + cohort routing).
- A Skip column showing which insights are already in Linear (they won't be pushed again).
Click Push and the issues are created in chunks of ~30 per second so SMP doesn't trip Linear's 1500-req/hour rate limit. Progress shows live; failures (a team renamed, a label conflict) are surfaced with skip / retry options.
Disconnecting
Click Disconnect on the connected card. You'll get a confirmation dialog explaining what happens:
- SMP stops creating new issues for your workspace.
- The Linear webhook is revoked — no more status sync into SMP.
- Existing Linear issues stay. Your team's open backlog isn't touched.
- Historical badges in SMP stay. Findings that were already sent to Linear keep their badge so you can still click through.
Re-connecting the same workspace later picks up where you left off (same row, fresh tokens, webhook re-registered). Findings you've already pushed keep their existing issue link — no duplicates.
Privacy and data handling
A few specifics about what travels between SMP and Linear:
- Tester identity stays anonymous. Linear sees tester aliases (e.g. "Sam", "Pat") and assistive technology used (NVDA, VoiceOver, etc). Linear never sees real names or contact details.
- No tester PII in webhook payloads. When Linear pushes status changes back to SMP, only the fields SMP needs for the timeline (state, priority, assignee identity from Linear's side, comment excerpts) are persisted. Linear's full webhook body is verified and dropped.
- Tokens are encrypted at rest. Your Linear OAuth tokens are AES-256-GCM encrypted in the SMP database. Decryption happens only inside the integration service, never in the browser or the Insights Portal frontend.
- Data residency. EU and AU customers' integration data stays in their regional SMP database. Your Linear workspace doesn't move — only metadata about which issues SMP has created.
Troubleshooting
"Authentication does not match this OAuth flow"
Status banner appears after authorising. This usually means the SMP session you started Connect in expired before you finished authorising on Linear's side. Sign back into SMP and retry from the Settings page.
"A Linear workspace is already connected for this organisation"
You can only connect one Linear workspace per SMP organisation in v1. Disconnect the existing workspace first, or push to the existing workspace if it's the right one.
Issues aren't appearing in the team I expected
Check your defaults on the Settings → Integrations connected card. If you set a team-level override on the per-push modal, that wins; otherwise the default team applies; otherwise cohort routing kicks in.
Status changes aren't syncing
Wait a few seconds — webhook delivery is fast but not instant. If status changes haven't synced after a minute or two, the webhook may have been removed in Linear directly. Disconnect and re-connect to register a fresh one.
Bulk push partially completed
If a bulk push fails mid-way (Linear rate limit, network blip, team renamed), the progress UI shows what succeeded. Re-running bulk push is safe — issues that already pushed are skipped via the idempotency check.
FAQ
Can I connect multiple Linear workspaces? v1 supports one Linear workspace per SMP organisation. Multi-workspace is on the roadmap.
Can I push individual tester findings (not just aggregated ones)? Yes. Both individual and aggregated insight types can be sent.
Will Linear labels be auto-created for severity / friction / cohort?
Not in v1 — the metadata travels in the issue description header (> **Severity:** high · **Friction:** navigation ...). Native Linear labels with brand colours land in v1.1.
What happens to issues SMP created if I revoke the integration in Linear directly? The issues stay in Linear. SMP stops syncing status. Disconnect and reconnect in SMP to re-establish the link.
Can my team write comments back into SMP from Linear? v1 surfaces Linear comments in the SMP timeline (excerpt + author + link) but doesn't push SMP comments to Linear. Two-way comment sync is on the roadmap.
How do I rotate the connection? Disconnect from SMP, optionally revoke the OAuth app in Linear's settings, then reconnect from SMP.
What's next on the roadmap
- Native Linear labels (severity, friction, WCAG, cohort) — one-click filter in Linear list views.
- Sub-issues for aggregate findings — each individual tester finding becomes a sub-issue, giving you a free "3 of 7 testers resolved" progress bar.
- Auto-resolution detection on re-test — when a re-test cohort doesn't reproduce the friction, SMP auto-comments on the Linear issue: "Re-tested 2026-08-12 with 5 testers — friction not observed. Safe to close?"
- Tester clip on assignee change — when someone picks up a Linear issue, SMP auto-comments with the most relevant 30-second tester clip: "Watch this before you start."
Need a capability that isn't here? Email your CSM — Linear integration feature requests are tagged and tracked for v1.1 prioritisation.