Linear Integration

Overview

DubPlanner integrates deeply with Linear to provide a seamless planning experience. Using industry-standard OAuth 2.0 authentication, DubPlanner securely connects to your Linear workspace without ever seeing your password.

Currently Supported

• Linear — full integration with bidirectional sync

Note

DubPlanner’s terminology is deliberately generic (“issue tracker” rather than “Linear”) in places, because the integration is built to be extended. Linear is the tracker it works with today.

How Authentication Works

DubPlanner uses OAuth 2.0 to authenticate with Linear:

What is OAuth 2.0?

OAuth 2.0 is the industry-standard protocol for authorization. Instead of sharing your Linear password with DubPlanner:

1. You log in directly to Linear
2. Linear asks if you want to grant DubPlanner access
3. You approve the requested permissions
4. Linear provides DubPlanner with a secure access token
5. DubPlanner uses the token to access Linear on your behalf

Why OAuth 2.0 is Secure

• No password sharing: DubPlanner never sees your Linear password
• Limited permissions: You grant only the access DubPlanner needs
• Revocable: You can revoke access anytime from your Linear settings
• Encrypted: Tokens are encrypted and stored securely

Learn more about security and token protection

Connecting to Linear

Initial Authentication

When you first use DubPlanner:

1. Visit DubPlanner: Navigate to the application URL
2. Click “Login with Linear”: The only authentication option
3. Redirected to Linear: Your browser goes to Linear’s OAuth page
4. Review Permissions: Linear shows what access DubPlanner is requesting:
   • Read your profile information
   • Read and modify issues
   • Read projects and teams
   • Read team members
5. Authorize: Click “Authorize” to grant access
6. Redirected Back: Linear sends you back to DubPlanner
7. You’re In: DubPlanner loads with your Linear projects

Tip

The entire authentication flow happens in your browser. DubPlanner’s backend server handles the secure token exchange with Linear’s servers.

What Permissions Are Needed

DubPlanner requests these Linear permissions:

• Read your profile: To show your name and avatar
• Read issues: To display issues in the planning grid
• Write issues: To update assignments, weeks, and status
• Read projects: To show available projects
• Read teams: To show team members
• Read milestones: To display milestone markers

DubPlanner only requests the permissions necessary for its functionality.

What Gets Synced

DubPlanner maintains a two-way sync with Linear:

From Linear to DubPlanner

These changes in Linear automatically appear in DubPlanner:

• New issues: Appear in the Backlog
• Issue updates: Title, description changes sync immediately
• Status changes: Updated status reflects in the grid
• Assignments: Team member assignments update
• Deletions: Removed issues disappear from DubPlanner
• Project changes: New projects appear in the project list

From DubPlanner to Linear

These changes in DubPlanner update Linear:

• Week assignments: Adds “Week[N]” labels to issues
• Status changes: Updates the issue’s workflow state — your project’s real Linear states
• Team assignments: Updates the assignee field
• Issue creation: New issues created from DubPlanner appear in Linear
• Deletions: Issues deleted in DubPlanner are removed from Linear

Week Labels in Linear

One of DubPlanner’s key features is automatic week label management:

How It Works

When you assign an issue to a week in DubPlanner:

1. DubPlanner checks if a “Week[N]” label exists in Linear
2. If not, it creates the label automatically
3. The label is applied to the issue
4. You can see the label in Linear’s issue view

Example: Assigning an issue to Week 5 adds the “Week5” label in Linear.

Why Week Labels?

Week labels provide several benefits:

• Visibility in Linear: You can see the planned week directly in Linear
• Filtering: Filter issues by week in Linear
• Integration: Other tools can read the week assignments
• Backup: Week information persists even if DubPlanner is offline

Workflow states are yours

DubPlanner reads your project’s workflow states from Linear and uses them as-is: your own Todo, In Progress, In Review, Done and any custom states, in Linear’s own order. Colour, icon and “does this count as finished?” are keyed off each state’s type, so renaming a state in Linear changes what you read in DubPlanner without changing how it behaves.

Milestones are likewise shown in the order you arranged them in Linear, everywhere they appear.

Staying signed in

Your Linear session is refreshed automatically in the background, so you are not asked to re-authorize every few days. If a session does expire, DubPlanner prompts you to sign in again rather than failing with a server error.

Managing Week Labels

Week labels are automatically:

• Created: By the first-run setup wizard, or on demand when first needed
• Added: When you assign an issue to a week
• Removed: When you move an issue out of a week
• Updated: When you move an issue to a different week

Tip

Week labels are named “Week1”, “Week2”, etc., starting from Week 1 of your project’s start date. They’re color-coded in Linear for easy identification.

Real-Time Collaboration

DubPlanner uses Firebase for real-time updates:

How It Works

• Instant sync: Changes appear within 1-2 seconds for all users
• User presence: See avatars of others viewing the same project
• No conflicts: Multiple users can work simultaneously safely

What Gets Broadcast

When you make a change:

• Other users see the issue move immediately
• Status changes appear in real-time
• Issue creation/deletion syncs instantly
• Availability changes update across sessions

Connection Status

If you lose internet connectivity:

• DubPlanner shows a connection warning
• Changes are queued locally
• Sync resumes when connection is restored
• You’re protected from data loss

Disconnecting from Linear

From DubPlanner

To disconnect your Linear account:

1. Open Settings in DubPlanner
2. Click “Disconnect from Linear”
3. Confirm the disconnection
4. You’re logged out and tokens are removed

From Linear

To revoke DubPlanner’s access from Linear:

1. Log into Linear
2. Go to Settings → Account → Authorized Applications
3. Find DubPlanner in the list
4. Click “Revoke Access”
5. DubPlanner can no longer access your Linear data

Caution

Revoking access from Linear immediately invalidates all tokens. You’ll be logged out of DubPlanner and need to re-authenticate to continue using it.

Reconnecting

To reconnect after disconnecting:

1. Visit DubPlanner
2. Click “Login with Linear”
3. Complete the OAuth flow again
4. Your previous planning data is still available

Permissions and Authorization

What You Can Do

DubPlanner respects Linear’s permission model:

• If you can view an issue in Linear, you can view it in DubPlanner
• If you can edit an issue in Linear, you can move it in DubPlanner
• If you can delete an issue in Linear, you can delete it in DubPlanner
• If you can create issues in Linear, you can create them in DubPlanner

Team Membership

• You only see projects you’re a member of in Linear
• Team members appear based on Linear project membership
• Admin permissions are checked for project settings

Data Isolation

• You can only access projects belonging to your organization
• Cross-organization data access is prevented
• Customer data is isolated at the API level

Learn more about security and permissions

Troubleshooting

Authentication Fails

Symptom: Can’t complete the “Login with Linear” flow

Solutions:

• Ensure you have a Linear account
• Check that your Linear workspace is active
• Try clearing browser cookies and trying again
• Verify you clicked “Authorize” (not “Deny”)

Issues Not Syncing

Symptom: Changes in Linear not appearing in DubPlanner (or vice versa)

Solutions:

• Check connection: Verify internet connectivity
• Refresh the page: Sometimes a manual refresh helps
• Check Linear status: Verify Linear API is operational
• Re-authenticate: Try disconnecting and reconnecting

Can’t See Projects

Symptom: Linear projects not appearing in DubPlanner

Solutions:

• Verify membership: Ensure you’re a member of the project in Linear
• Check project status: Archived projects may not appear
• Refresh: Try reloading the project list
• Re-authenticate: Log out and back in

Permission Denied

Symptom: Can’t edit issues or move them in the grid

Solutions:

• Check Linear permissions: Verify you have edit access in Linear
• Team membership: Ensure you’re a member of the relevant team
• Issue state: Some workflow states may be read-only
• Refresh tokens: Try logging out and back in

Week Labels Not Creating

Symptom: “Week[N]” labels not appearing in Linear

Solutions:

• Check label permissions: Verify you can create labels in Linear
• Wait a moment: Label creation can take a few seconds
• Refresh Linear: Reload Linear to see new labels
• Check API limits: Linear API rate limits may delay label creation

API Rate Limits

Linear enforces API rate limits:

• Typical limit: ~1500 requests per hour per user
• DubPlanner optimization: Batches requests to minimize API calls
• Rare impact: Most users won’t hit limits with normal use
• If exceeded: DubPlanner pauses briefly then retries

Note

DubPlanner uses real-time subscriptions (webhooks) where possible to reduce API calls and provide faster updates.

Data Privacy

What DubPlanner Stores

• Access tokens: Encrypted and stored securely in Google Cloud Firestore
• User profile: Name, email, avatar (from Linear)
• Planning data: Week assignments, availability schedules
• Session data: Active sessions for real-time collaboration

What DubPlanner Does NOT Store

• Passwords: Never stored (OAuth authentication only)
• Credit cards: No payment processing
• Issue content: Issue details are fetched from Linear in real-time
• Files/attachments: Linear attachments remain in Linear

Learn more about data privacy and security

Best Practices

Security

• Revoke unused access: If you stop using DubPlanner, revoke access from Linear
• Review permissions: Periodically check authorized applications in Linear
• Report issues: Report security concerns immediately

Integration

• Regular sync: Keep DubPlanner and Linear in sync by using both regularly
• Consistent status: Update status in one place (either tool)
• Week labels: Don’t manually edit “Week[N]” labels—let DubPlanner manage them
• Backup important data: Linear is the source of truth

Collaboration

• Communicate changes: Let team know when you make large changes
• Use real-time features: Take advantage of instant sync for collaboration
• Check who’s online: See user avatars to know who else is planning

Future Enhancements

Planned Linear integration improvements:

• Webhook optimization: Faster real-time updates
• Offline support: Work without internet, sync when reconnected
• Bulk operations: Move multiple issues more efficiently
• Custom fields: Sync Linear custom fields
• Attachments: View Linear attachments in DubPlanner

Next Steps

• Start planning with your Linear issues
• Learn about team availability
• Understand the security architecture