Linear Integration

This guide helps an Admin connect and configure Linear for one workspace.

Quick Actions

What the Linear Integration Does

• Links Superfeedback tickets to Linear issues.
• Keeps status changes synchronized in both directions.
• Applies default assignee, project, labels, and priority for synced issues.
• Supports backfilling open tickets into Linear in chunks.

Prerequisites

• Admin access in the Superfeedback workspace.
• A Linear account with access to the target organization.
• Linear admin-level permission to create webhooks during setup.

Required OAuth scopes shown in product setup:

• Read access to the Linear workspace.
• Write access to the Linear workspace.
• Admin access to manage settings and people (required for webhook creation).

Connect Linear

1. Open Integrations in your workspace dashboard.
2. Select Linear.
3. Click Connect Linear.
4. Complete the Linear OAuth flow and accept required scopes.
5. Confirm the connection badge shows Connected.

If setup completes authentication but webhook setup fails, reconnect with a Linear admin account.

Configure the Integration

1. Connection

• Enable or disable sync for this connection.
• Mark the connection as default for automated Linear actions.
• Select a default Linear team for routing and catalog sync.
• Save with Save connection.

2. Status Mapping

• Use one row per Linear state.
• Map each Linear state to a Superfeedback status.
• Set fallback mappings for each status type:
  • Fallback from Superfeedback: used when a Superfeedback type has no direct Linear state.
  • Fallback from Linear: used when a Linear type has no direct Superfeedback status.
• Click Sync statuses from Linear to refresh state catalog after changes in Linear.
• Save with Save mappings.

3. Issue Defaults

Choose what is included in issue descriptions:

• Summary
• Original ticket content
• Representative user quotes
• Ticket link back to Superfeedback

Set default values for new/updated Linear issues:

• Default assignee
• Default project
• Default priority
• Default labels

Save with Save defaults.

4. Backfill and Diagnostics

• Run Start backfill to link open existing tickets to Linear in chunks of 20.
• Stop a running backfill if needed.
• Track processed, created, linked, skipped, and failed counts.
• Use technical fields (connection ID, organization, default team) for debugging.

Expected Result

• New Superfeedback tickets can sync to Linear.
• Status changes remain aligned in both tools.
• Backfill links legacy open tickets without manual recreation.

Ongoing Workflow

1. Triage feedback in Superfeedback as usual.
2. Link tickets to Linear where execution should happen.
3. Monitor status alignment in both systems.
4. Re-sync status catalog if your team changes workflow states in Linear.

Need Help?

Use Linear Troubleshooting for common setup and sync failures.