Linear Integration
Connect Outpost to Linear for bidirectional issue synchronization. Tickets created in Outpost appear as Linear issues, and changes in Linear flow back to Outpost automatically.
Setup
1. Create a Linear API Key
- Go to Linear Settings → API
- Click Create key
- Give it a descriptive label (e.g., "Outpost Sync")
- Copy the generated key — this is your
LINEAR_API_KEY
2. Configure a Webhook
- Go to Linear Settings → API → Webhooks
- Click Create webhook
- Set the URL to
https://your-outpost-domain.com/api/linear/webhook - Select the events to subscribe to:
- Issues — create, update, remove
- Comments — create, update, remove
- Labels — create, update, remove
- Copy the Webhook secret shown after creation — this is your
LINEAR_WEBHOOK_SECRET
3. Find Your Team ID
- In Linear, go to Settings → Teams
- Click on the team you want to sync with Outpost
- The team ID is in the URL:
https://linear.app/your-org/settings/teams/TEAM_ID
Environment Variables
# Linear Integration
LINEAR_API_KEY=lin_api_your-api-key-here
LINEAR_WEBHOOK_SECRET=your-webhook-signing-secret
LINEAR_TEAM_ID=your-linear-team-idWebhook URL: The Linear webhook endpoint must be publicly accessible. During local development, use a tunneling tool like ngrok to expose your local server. The webhook receiver runs on the same port as the Outpost web app (default 3000).
Status Mapping
Linear uses configurable workflow states per team. Outpost maps these to its own ticket statuses. The default mapping is:
| Linear Workflow State | Outpost Status |
|---|---|
| Backlog | open |
| Todo | open |
| In Progress | in_progress |
| In Review | in_progress |
| Done | resolved |
| Canceled | closed |
When an Outpost ticket status changes, the corresponding Linear issue is moved to the first matching workflow state. Custom status mappings can be configured in the admin dashboard under Settings → Sync → Linear.
Priority Mapping
Linear priorities (0–4) map to Outpost priorities as follows:
| Linear Priority | Linear Label | Outpost Priority |
|---|---|---|
| 0 | No priority | low |
| 1 | Urgent | critical |
| 2 | High | high |
| 3 | Medium | medium |
| 4 | Low | low |
Identity Mapping
To sync assignees between Linear and Outpost, each Linear user must be linked to an Outpost TeamMember. This is configured in the admin dashboard under Settings → Team Members by adding each member's Linear user ID to their profile.
When a Linear issue is assigned to a user with a linked TeamMember, the corresponding Outpost ticket is automatically assigned to that team member (and vice versa). Unlinked users are ignored for assignment sync, but their names still appear in synced comments.
What Syncs
The following fields are synchronized bidirectionally between Outpost and Linear:
| Field | Direction | Details |
|---|---|---|
| Status | Bidirectional | Mapped via status mapping (see above) |
| Priority | Bidirectional | Mapped via priority mapping (see above) |
| Assignee | Bidirectional | Requires identity mapping |
| Labels | Bidirectional | Linear labels ↔ Outpost tags |
| Comments | Bidirectional | Markdown preserved, author attributed |
| Title | Bidirectional | Issue title ↔ ticket title |
| Description | Outpost → Linear | Set on initial creation only |
Bulk Import
When you first connect Linear, you can import existing issues into Outpost as tickets. This is useful for migrating an existing workflow or catching up on issues created before the integration was enabled.
- Go to the admin dashboard: Settings → Sync → Linear
- Click Import existing issues
- Select which Linear statuses to import (e.g., skip "Done" and "Canceled" issues)
- The import runs as a background job — progress is shown in the dashboard
Duplicate prevention: The bulk import checks for existing linked tickets before creating new ones, so it is safe to run multiple times. Issues already linked to Outpost tickets are skipped.
Webhook Events
The Linear webhook endpoint at /api/linear/webhook handles the following events:
| Event | Action |
|---|---|
| Issue create | Creates a new Outpost ticket linked to the Linear issue |
| Issue update | Syncs status, priority, assignee, and label changes |
| Issue remove | Closes the linked Outpost ticket |
| Comment create | Adds the comment as a message on the linked ticket |
| Comment update | Updates the corresponding message in Outpost |
| Comment remove | Marks the message as deleted in Outpost |
All webhook payloads are verified using the LINEAR_WEBHOOK_SECRET to ensure
authenticity. Invalid signatures are rejected with a 401 response.