Connect Your Linear Workspace

Integration Hub uses OAuth to securely connect to your Linear workspace. This ensures secure access to your teams, issues, and projects while maintaining full control over permissions.

Before You Begin

Connection Steps

Step 1: Navigate to Connections

1. Log in to Integration Hub
2. Navigate to the Connections tab in the main navigation
3. Find the Linear connection card
4. Ensure you've already connected your PagerDuty account

Screenshot: Linear connection card

Step 2: Authorize with OAuth

1. Click the Connect Linear button
2. You'll be redirected to Linear's OAuth authorization page
3. Select the workspace you want to connect (if you have multiple)
4. Review the requested permissions:
   • Read and write issues
   • Read teams and projects
   • Create and manage webhooks
   • Read and write comments
   • Read user information
5. Click Authorize to grant access

Screenshot: OAuth authorization page

Step 3: Confirm Connection

After authorization, you'll be redirected back to Integration Hub. You should see:

• A success message confirming the connection
• Your Linear workspace name displayed
• Connection status showing as Connected
• A list of your accessible teams
• The option to disconnect if needed

Screenshot: Connected Linear workspace

What Happens Next

Once connected, Integration Hub can:

• Read Your Teams - View all teams you have access to for webhook configuration
• Monitor Issues - Receive updates when issues are created or modified
• Update Issues - Sync PagerDuty incident status changes back to Linear
• Add Comments - Sync PagerDuty notes as comments on Linear issues
• Create Webhooks - Set up webhooks per team for real-time updates
• Read Projects and Labels - Access project and label information for rule filtering

Understanding Linear Teams

Linear organizes work into teams. Each team has its own issues, projects, and workflows. Integration Hub creates webhooks on a per-team basis, which means:

• You can integrate specific teams without affecting others
• Each team can have different rules for incident creation
• Webhooks only receive updates for their respective team's issues

Accessing Projects and Labels

Projects

Once connected, Integration Hub can access all projects within your Linear teams. When creating rules, you can filter incidents by specific projects:

• Monitor only production-related projects
• Create separate rules for different project types
• Route project-specific issues to appropriate PagerDuty services

Labels

Integration Hub can also read Linear labels, allowing you to filter incidents based on:

• Issue severity (Critical, High, Medium, Low)
• Environment labels (Production, Staging, Development)
• Custom labels specific to your workflow

Security and Permissions

OAuth Token Storage

Integration Hub stores your Linear OAuth token securely:

• Encrypted at rest using industry-standard encryption
• Never exposed in logs or error messages
• Only used for operations you've configured
• Automatically refreshed when needed

Team Access Scope

Integration Hub can only access teams that your Linear account has permission to view. If you don't see a team when creating webhooks, verify your Linear account has access to that team.

Revoking Access

You can revoke Integration Hub's access at any time:

1. From Integration Hub: Click the Disconnect button in the Connections tab
2. From Linear: Go to Settings → My Account → Applications and revoke access

Troubleshooting

Authorization Failed

Problem: OAuth authorization fails or times out

Solution:

• Verify you're logged into the correct Linear workspace
• Check that you have Member or Admin role
• Clear browser cookies and try again
• Try a different browser or incognito mode

Teams Not Showing

Problem: Some teams don't appear when creating webhooks

Solution:

• Verify your Linear account has access to those teams
• Ask a workspace admin to grant you access to the teams
• Refresh the page to reload team data
• Disconnect and reconnect to refresh permissions

Connection Shows as Disconnected

Problem: Connection status changes to "Disconnected" after successful authorization

Solution:

• Check if the OAuth token was revoked in Linear settings
• Verify your account still has the required permissions
• Check if your Linear workspace is still active
• Reconnect by clicking the Connect Linear button again

Webhooks Not Receiving Updates

Problem: Webhooks created but not receiving issue updates

Solution:

• Verify the webhook is enabled in the Webhooks tab
• Check that the Linear connection status is "Connected"
• Verify Linear hasn't disabled the webhook (check Linear Settings → Webhooks)
• Test the webhook by creating or updating an issue in the connected team

Multiple Linear Workspaces

Integration Hub supports connecting to one Linear workspace at a time. If you need to switch workspaces:

1. Click Disconnect to remove the current connection
2. Click Connect Linear again
3. When prompted, log in to the different Linear workspace
4. Authorize the new workspace

Verifying Team Access

To verify which teams Integration Hub can access:

1. Navigate to the Webhooks tab
2. Click Create Webhook
3. View the list of available teams in the team selector

If a team is missing from this list, you need to request access from your Linear workspace admin.

Next Steps

Now that you've connected both PagerDuty and Linear, you're ready to set up the integration:

1. Create Webhooks for Your Teams →
2. Configure Rules to Create Incidents →
3. Learn About Bidirectional Sync →