Overview#
The Shorter Loop and Linear integration allows you to seamlessly sync your Linear issues with Shorter Loop, enabling better project visibility and collaboration across your teams. This integration automatically keeps your work items synchronized between both platforms.What You Can Do#
With this integration, you can:Connect Linear Teams to your Shorter Loop workspace
Automatically sync issues from Linear to Shorter Loop product backlog user stories.
Real-time updates via webhooks when issues change in Linear
Track progress across both platforms simultaneously
Maintain single source of truth while working in either tool
Getting Started#
Prerequisites#
Before you begin, make sure you have:✅ Admin access to your Linear workspace
✅ A Shorter Loop account with an active initiative
✅ Linear API credentials (Client ID and Client Secret)
You'll need to create an OAuth application in Linear to get your Client ID and Client Secret. Contact your Linear workspace administrator if you don't have these credentials.
Setting Up the Integration#
Step 1: Obtain Linear API Credentials#
1.
Log in to your Linear workspace
2.
Navigate to Settings → API → OAuth applications
3. Click Create new application
4. Fill in the application details:Name: Shorter Loop Integration
Redirect URI: (provided by Shorter Loop)
Scopes: Select read and write permissions
5.
Save the application and copy your Client ID and Client Secret
Keep your Client Secret secure! Treat it like a password and never share it publicly.
Step 2: Connect Linear to Shorter Loop#
1.
In Shorter Loop, navigate to your Initiative Settings
2.
Go to the Integrations section
3.
Click on Linear integration
4.
Enter your Linear credentials:Client ID: Paste the Client ID from Linear
Client Secret: Paste the Client Secret from Linear
Step 3: Select Teams to Sync#
1.
After successful connection, you'll see a list of all your Linear teams
2.
Select the team(s) you want to sync with Shorter Loop
3.
Map each Linear team to a corresponding Shorter Loop team
You can connect multiple Linear teams to different Shorter Loop teams within the same initiative.
How Synchronization Works#
Initial Import#
When you first connect a Linear team:1.
All existing issues from the selected Linear team are imported into Shorter Loop
2.
Issues are created as User Stories in your Shorter Loop backlog
3.
The following information is synced:Issue identifier (e.g., ENG-123)
Direct link to Linear issue
Real-Time Updates (Webhooks)#
After the initial import, Shorter Loop sets up a webhook with Linear to receive real-time updates:When an issue is created in Linear → Automatically created in Shorter Loop
When an issue is updated in Linear → Corresponding item updated in Shorter Loop
When status changes in Linear → Progress updated in Shorter Loop
Status Mapping#
Linear statuses are automatically mapped to Shorter Loop progress states:| Linear Status | Shorter Loop Progress |
|---|
| To Do | To-Do |
| In Progress | In-Progress |
| Done | Done |
| Other statuses | In-Progress (default) |
Managing Your Integration#
Viewing Connected Teams#
1.
Go to Initiative Settings → Integrations
3.
You'll see all connected Linear teams and their sync status
Disconnecting a Team#
To disconnect a specific Linear team:1.
Navigate to Initiative Settings → Integrations → Linear
2.
Find the team you want to disconnect
3.
Click Disconnect next to the team name
4.
Confirm the disconnection
Disconnecting a team will stop future synchronization, but existing synced items will remain in Shorter Loop.
Unlinking the Entire Integration#
To completely remove the Linear integration:1.
Navigate to Initiative Settings → Integrations → Linear
This will disconnect all Linear teams and stop all synchronization. Existing work items will remain in Shorter Loop but will no longer sync with Linear.
Understanding Synced Data#
What Gets Synced#
✅ Synced from Linear to Shorter Loop:Issue identifier (e.g., ENG-123)
Direct URL to Linear issue
Data Flow Direction#
This is a one-way sync from Linear to Shorter Loop. Changes made in Shorter Loop will NOT sync back to Linear.
Troubleshooting#
Connection Issues#
Problem: "Failed to verify Linear credentials"Verify your Client ID and Client Secret are correct
Ensure your Linear OAuth application has the correct scopes (read and write)
Check that your Linear account has admin permissions
Problem: "No teams found"Verify you have teams created in your Linear workspace
Ensure your API credentials have access to view teams
Try disconnecting and reconnecting the integration
Sync Issues#
Problem: "Issues not syncing from Linear"Check that the webhook is properly configured in Linear
Verify the team is still connected in Shorter Loop
Try disconnecting and reconnecting the specific team
Problem: "Status not updating correctly"Verify the issue status in Linear matches one of the supported states
Check that the webhook is active
Manual refresh: disconnect and reconnect the team to re-sync
Best Practices#
🎯 Team Organization#
Map teams logically: Connect Linear teams to corresponding Shorter Loop teams based on your organizational structure
Start small: Begin by connecting one team to test the integration before scaling up
Regular reviews: Periodically review your connected teams to ensure they're still relevant
📊 Data Management#
Clean data first: Ensure your Linear issues are well-organized before connecting
Use labels effectively: Labels sync as tags, so maintain consistent labeling in Linear
Monitor initial import: Watch the first sync to ensure all expected issues are imported
🔄 Workflow Integration#
Keep Linear as source: Since sync is one-way, continue managing issues in Linear
Use Shorter Loop for planning: Leverage Shorter Loop's planning features while keeping Linear as your issue tracker
Communicate changes: Inform your team about the integration and how data flows
🔒 Security#
Protect credentials: Never share your Client ID and Client Secret
Regular audits: Periodically review connected integrations and remove unused ones
Access control: Ensure only authorized team members can modify integration settings
Frequently Asked Questions#
Can I sync from Shorter Loop back to Linear?#
No, this is currently a one-way integration from Linear to Shorter Loop. Changes in Shorter Loop do not sync back to Linear.What happens to existing Shorter Loop items when I connect Linear?#
Existing items remain unchanged. The integration only creates new items from Linear issues.Can I connect multiple Linear workspaces?#
Yes, you can connect different Linear teams from the same workspace to different Shorter Loop teams.Will disconnecting delete my synced items?#
No, disconnecting stops future synchronization but preserves all existing synced items in Shorter Loop.How often does the sync happen?#
Initial sync: Happens immediately when you connect a team
Updates: Real-time via webhooks whenever changes occur in Linear
Can I customize which fields sync?#
Field mapping is currently automatic and cannot be customized. All supported fields sync by default.
Getting Help#
If you encounter issues not covered in this guide:1.
Check the status: Verify your integration is still connected
2.
Review credentials: Ensure your Linear API credentials are valid
3.
Contact support: Reach out to Shorter Loop support with:Any error messages you received
Summary#
The Linear integration streamlines your workflow by automatically syncing issues from Linear into Shorter Loop, giving you a unified view of your work across both platforms. With real-time updates and automatic status mapping, your teams can work seamlessly while maintaining data consistency.✅ One-way sync from Linear to Shorter Loop
✅ Real-time updates via webhooks
✅ Automatic status mapping
✅ Support for multiple teams
✅ Simple setup with OAuth credentials
