Linear integration
Connect and sync Linear issues with a Ragnarock project.
Linear connects at two levels: organization OAuth and per-project mapping.
Setup
Connect Linear under Organization → Integrations (/dashboard/organization/integrations).
API: POST /integrations/linear with OAuth callback handling.
Open the project Linear page (/dashboard/projects/{projectId}/linear).
Link the Ragnarock project to a Linear team/project — POST /projects/:projectId/linear/link.
Configure sync settings — PATCH /projects/:projectId/linear/settings.
Run import or export — POST .../linear/import or POST .../linear/export.
API surface
| Method | Path | Purpose |
|---|---|---|
GET | /integrations/linear/teams | List Linear teams |
GET | /integrations/linear/projects | List Linear projects |
GET | /projects/:projectId/linear | Sync status |
POST | /projects/:projectId/linear/sync | Trigger sync |
GET | /projects/:projectId/linear/sync-runs | History |
POST | /webhooks/linear | Inbound webhook (backend) |
Sync behavior
- Issues link to Ragnarock requirements/tasks via
LinearIssueLinkrecords. - Sync runs are logged in
LinearSyncRunfor debugging. - Outbound calls use Linear GraphQL (
linear-graphql.service.ts).
Avoid editing the same issue field in both systems simultaneously. Pick one system as canonical for status and assignee.
Troubleshooting
| Symptom | Check |
|---|---|
| OAuth redirect error | BETTER_AUTH_URL, Linear app callback URLs |
| Empty team list | Org integration token expired — reconnect |
| Webhook not firing | Public URL reachable; webhook secret in backend env |
| Stale issues | Run manual sync; inspect latest sync-runs |
See Common issues and GitHub for repo linking (often used alongside Linear).