Linear Integration

Overview

The Linear integration connects your retrospective action items directly to Linear's issue tracker. When your team commits to action items during a retrospective, Unpack can create corresponding Linear issues with the correct team, labels, and assignee. This keeps your improvement work visible alongside feature development and bug fixes.

Connecting Linear

Unpack connects to Linear through OAuth 2.0. The authorization flow grants Unpack access to create issues, read team and label data, and register webhooks on your Linear workspace.

1. Navigate to Organization Settings → Integrations.
2. In the Linear card, click Connect to Linear.
3. You will be redirected to Linear's authorization page. Sign in if prompted and review the permissions Unpack is requesting.
4. Click Authorize to grant access.
5. You will be redirected back to Unpack. A confirmation banner confirms the connection along with your Linear workspace name.

After connecting, Unpack automatically imports your Linear workspace's teams and labels to make configuration easier. This import happens once during setup and can be refreshed at any time.

Configuring Sync Settings

After connecting Linear, configure how Unpack maps action items to Linear issues.

1. Navigate to Organization Settings → Integrations → Linear.
2. Under Default Team, select the Linear team where action items should be created. The dropdown lists all teams imported from your Linear workspace.
3. Optionally, under Default Labels, select one or more labels to apply to every issue created by Unpack. A common pattern is to create a "Retrospective" label in Linear so these issues are easy to filter.
4. Enable Per-Team Overrides if you want different Unpack teams to sync to different Linear teams.
5. Click Save Settings.

Field Mapping

Unpack maps action item fields to Linear issue fields as follows:

• Title → Linear issue Title
• Description → Linear issue Description (Markdown format)
• Assignee → Linear issue Assignee (matched by email address)
• Due date → Linear issue Due Date
• Labels → Default labels configured in integration settings
• Retrospective link → Appended to the description as a reference

Importing Metadata

During the initial connection, Unpack imports teams and labels from your Linear workspace. This metadata is used to populate dropdowns in the integration settings and to match assignees.

Teams

Unpack imports all Linear teams that the authorized account has access to. Each team's name, key, and member list are stored so that Unpack can present accurate options in the configuration UI and match assignees by email.

Labels

Workspace-level and team-level labels are imported so you can assign default labels to synced issues. If you create new labels in Linear after the initial import, use the refresh function to update the list in Unpack.

Refreshing Team Members

As people join or leave your Linear workspace, the member list in Unpack may become stale. Refreshing ensures that assignee matching works correctly for new team members.

1. Navigate to Organization Settings → Integrations → Linear.
2. Click the Refresh Metadata button at the top of the settings panel.
3. Unpack will re-import teams, labels, and team members from Linear. A progress indicator shows the import status.
4. Once complete, a confirmation message displays the number of teams and members imported.

How Sync Works

Action items are synced to Linear when a retrospective enters the Commit phase. Unpack creates one Linear issue per action item. Each synced action item displays a Linear issue identifier (for example, ENG-87) that links directly to the issue in your Linear workspace.

If you update an action item's title, description, or assignee in Unpack after the initial sync, the changes are pushed to the corresponding Linear issue on the next sync cycle.

Webhook Events from Linear

Unpack can receive webhook events from Linear to keep action item statuses in sync. When enabled, Unpack registers a webhook that listens for issue status changes.

1. Navigate to Organization Settings → Integrations → Linear.
2. Under Webhooks, toggle Enable Linear Webhooks on.
3. Click Save Settings.

When a Linear issue created by Unpack is moved to a completed state (such as "Done" or "Canceled"), the corresponding action item in Unpack is updated to reflect that status. This provides two-way visibility without requiring anyone to update both tools manually.

Retry and Manual Sync

If a sync fails, Unpack retries automatically up to three times. Failed syncs appear in the sync log with an error message and a Retry button.

You can also manually sync individual action items from the retrospective view:

1. Open the retrospective and navigate to the Action Items panel.
2. Click the overflow menu (…) on the action item.
3. Select Sync to Linear.

Disconnecting Linear

1. Navigate to Organization Settings → Integrations → Linear.
2. Click Disconnect Linear at the bottom of the page.
3. Confirm the disconnection in the dialog.

Disconnecting removes the OAuth token, unregisters webhooks, and stops all syncing. Linear issues that were already created will remain in your workspace. The issue identifiers displayed on action items in Unpack will continue to link to the issues, but no further updates will be synced in either direction.

Troubleshooting

• Sync fails with "team not found": The target Linear team may have been archived or renamed. Click Refresh Metadata and update the team selection in your settings.
• Assignee not matched: Ensure that the team member's email address in Unpack matches their Linear account email. Refresh metadata to pull in the latest member list.
• Labels not appearing: New labels created after the initial import require a metadata refresh. Click Refresh Metadata to update the label list.
• Webhook events not processing: Verify that webhooks are enabled in the integration settings. Check the sync log for any delivery errors.