Linear Integration
GuideMode integrates with Linear to provide visibility into your project management workflow. This integration enables team sync, real-time issue tracking via webhooks, and links Linear work items to your development analytics.
What You Get
Section titled “What You Get”- Team & User Sync: Sync Linear teams and users to GuideMode for team-based analytics
- Issue Tracking: Real-time updates on issues via automatic webhooks
- Project Tracking: Monitor Linear projects and their issues
- Label Mapping: Map Linear labels to GuideMode’s analytical categories
Prerequisites
Section titled “Prerequisites”Before setting up the Linear integration, you’ll need:
- A Linear account with admin access to your workspace
- Admin permissions in your GuideMode tenant
Setup Overview
Section titled “Setup Overview”The Linear integration uses:
- OAuth Connection - For authentication and API access (GuideMode handles the OAuth app)
- Automatic Webhooks - For real-time issue updates (created automatically on connection)
Step 1: Connect with Linear
Section titled “Step 1: Connect with Linear”- Navigate to Settings > Integrations > Linear in GuideMode
- Click Connect with Linear
- Authorize GuideMode to access your Linear workspace
- Your workspace is automatically detected from your account
- You’ll be redirected back to GuideMode once connected
Organization Sync
Section titled “Organization Sync”After connecting, you can sync your Linear workspace data to GuideMode.
Sync Types
Section titled “Sync Types”GuideMode offers two sync options:
| Sync Type | What’s Synced | Best For |
|---|---|---|
| Sync Organisation | Users and Teams only | Quick team setup |
| Sync All | Users, Teams, Projects, and Issues | Full data import |
Triggering a Sync
Section titled “Triggering a Sync”- Go to Settings > Integrations > Linear
- Choose your sync type:
- Click Sync Organisation for teams and users only
- Click Sync All for complete data including projects and issues
- Monitor progress in real-time (status updates automatically)
What Gets Synced
Section titled “What Gets Synced”| Data | Description |
|---|---|
| Users | Linear workspace members |
| Teams | All workspace teams |
| Projects | Linear projects (full sync only) |
| Issues | Project issues with status and labels (full sync only) |
Webhook Events
Section titled “Webhook Events”Linear webhooks are configured automatically when you connect your workspace. No manual setup is required.
Automatic Configuration
Section titled “Automatic Configuration”When you connect Linear, GuideMode automatically registers webhooks for:
- Issues: Created, updated, deleted
- Issue Labels: Label changes
- Projects: Created, updated
- Users: Added, updated
Real-Time Updates
Section titled “Real-Time Updates”Changes in Linear are reflected in GuideMode within seconds. The webhook captures:
- Issue state changes (open, in progress, closed)
- Label additions and removals
- Assignment changes
- Project updates
Issue Type Mapping
Section titled “Issue Type Mapping”GuideMode maps Linear labels to canonical issue types for consistent analytics across projects.
See Issues → Type Mapping for the default label heuristics and how to configure custom mappings.
Custom Label Mappings
Section titled “Custom Label Mappings”You can configure custom mappings in Settings > Integrations > Linear > Label Mappings. Custom mappings take priority over default heuristics.
Issue State Tracking
Section titled “Issue State Tracking”Linear provides rich state information. GuideMode maps Linear statuses to canonical states:
| Linear Status | GuideMode State |
|---|---|
| Backlog, Triage, Todo | open |
| In Progress, In Review | in_progress |
| Done, Canceled | closed |
Data Management
Section titled “Data Management”Disconnect Linear
Section titled “Disconnect Linear”To disconnect your Linear workspace:
- Go to Settings > Integrations > Linear
- Click Disconnect
- Confirm the disconnection
This removes the OAuth connection but preserves synced data.
Delete All Linear Data
Section titled “Delete All Linear Data”To remove all Linear data from GuideMode:
- Go to Settings > Integrations > Linear
- In the Danger Zone, click Delete All Linear Data
- Type
DELETE ALL LINEAR DATAto confirm - Click Delete
This removes all synced issues, projects, teams, and sync logs while keeping your OAuth connection.
Troubleshooting
Section titled “Troubleshooting”Connection Fails
Section titled “Connection Fails”- Ensure you’re logged into the correct Linear account
- Try disconnecting and reconnecting in Settings > Integrations > Linear
- Check that you have admin access to the Linear workspace
Sync Fails or Incomplete
Section titled “Sync Fails or Incomplete”- Verify you have admin permissions in both Linear and GuideMode
- Check for any error messages in the sync status
- Try triggering a new sync after a few minutes
Missing Team Data
Section titled “Missing Team Data”- Ensure teams exist in your Linear workspace
- Trigger a manual sync from Settings > Integrations > Linear
- Verify your Linear account can view the teams
Issues Not Updating
Section titled “Issues Not Updating”- Webhooks are automatic; check your connection status
- If issues persist, disconnect and reconnect to re-register webhooks
- Verify the workspace has the correct permissions
Labels Not Mapping Correctly
Section titled “Labels Not Mapping Correctly”- Review your custom mappings in Settings > Integrations > Linear > Label Mappings
- Check that label names match (case-insensitive)
- Use default heuristics as a guide for naming labels
Related Documentation
Section titled “Related Documentation”Core Concepts
Section titled “Core Concepts”- Issues - Canonical issue types and lifecycle
- Teams - Team structure and sync
- Projects - Project tracking
Analytics
Section titled “Analytics”- Delivery Flow - Issue metrics and cycle time
- How It Works - DX² methodology