Complete Setup Guide
Learn how to connect your HubSpot account and configure the Linear integration to streamline your development workflow and customer support processes.
Table of Contents
Installation & Configuration
Usage & Support
Integration Overview
The Linear-HubSpot integration provides three powerful ways to connect your project management and customer support workflows:
App Card
Interactive card in HubSpot tickets for managing Linear issues
- View Linear issue details
- Create new issues from tickets
- Update status and assignees
Workflow Actions
Automated Linear issue creation through HubSpot workflows
- Trigger on ticket events
- Custom field mapping
- Conditional logic
Webhook Sync
Real-time bidirectional synchronization
- Status updates
- Comment synchronization
- Assignee changes
Prerequisites
Before installing the integration, ensure you have the following:
HubSpot Requirements
- HubSpot Professional or Enterprise account
Required for workflow automation features
- Admin or Super Admin permissions
Needed to install apps and configure workflows
- Service Hub or Sales Hub
For ticket management capabilities
Linear Requirements
- Linear workspace with API access
Standard or higher plan recommended
- Workspace admin permissions
To create OAuth apps and configure webhooks
- Teams and projects set up
For proper issue organization
Step 1: Connect Your HubSpot Account
To integrate Linear with your HubSpot account, please follow these steps:
Step 1: Go to the signup to begin setup process.
Go to SignupStep 2: After submission you will be redirected to HubSpot to authorize the app.
Step 3: Enter your HubSpot credentials and hit "Login."
Step 4: Click on the "choose account" button to give the app access to your account.
Step 5: Grant the required permissions to complete the connection.
After completing these steps, you will be redirected to the Setup Dashboard, where you can continue configuring the integration.
Required HubSpot Permissions
The integration requires the following permissions:
- • tickets - Read and write access to support tickets
- • crm.objects.owners.read - Access to user information
- • oauth - OAuth token management
- • automation - Workflow automation capabilities
Uninstall
To uninstall the integration from your HubSpot account, follow the instructions in this HubSpot Knowledge Base article.
Step 2: Connect Your Linear Workspace
Now connect your Linear workspace to create issues from HubSpot tickets.
Linear Connection Process
HubSpot Connected
After completing the HubSpot connection, you'll automatically proceed to the Linear connection step.
Click Connect Linear
Click "Connect Linear Workspace" to start the Linear OAuth process.
Authorize Linear Access
You'll be redirected to Linear to authorize the integration. Grant access to your workspace.
What we'll access:
- • Your Linear workspace
- • Teams and projects
- • Issue creation permissions
- • Issue status updates
- • Comment synchronization
Important: Workspace Limitation
Each Linear workspace can only be connected to one HubSpot portal at a time. If you try to connect a workspace that's already connected to another portal, you'll receive an error message with details about the existing connection.
Step 3: Choose Your Plan
Select a plan to continue using the integration after your trial period.
Linear Connected!
Your Linear workspace is ready for integration.
Choose Your Preferred Plan
Monthly Plan
Yearly Plan
Free Trial Information
- • 14-day free trial - No payment required during trial period
- • Cancel anytime - No commitment, cancel your subscription at any time
- • Full access - All features available during the trial period
Payment Process
Select Plan
Choose between monthly ($19/month) or yearly ($199/year) plan.
Secure Payment
Complete payment through Stripe's secure checkout process.
Start Trial
Begin your 14-day free trial immediately after payment setup.
Step 4: Complete Setup
After payment setup, complete the integration configuration and start using your Linear-HubSpot integration.
Payment Completed!
Your subscription is now active and you can proceed to complete the setup.
Linear Settings Configuration
Access the Linear settings page to configure workspace-specific options:
Available Settings
Issue Creation
- • Enable/disable ticket creation
- • Default team assignment
- • Default project assignment
- • Priority mapping
Synchronization
- • Bidirectional sync toggle
- • Comment synchronization
- • Status mapping
- • Assignee synchronization
Field Mapping
Configure how HubSpot ticket properties map to Linear issue fields:
| HubSpot Property | Linear Field | Description |
|---|---|---|
| Subject | Title | Ticket subject becomes issue title |
| Content/Description | Description | Ticket content becomes issue description |
| Priority | Priority | Mapped priority levels |
| Category | Labels | Ticket category becomes issue labels |
| Owner | Assignee | Ticket owner becomes issue assignee |
Step 5: App Card Configuration
Set up the Linear Issue Converter card in your HubSpot tickets for interactive issue management.
Card Features
Issue Creation
Create new Linear issues directly from HubSpot tickets
Issue Linking
Link existing Linear issues to tickets
Status Updates
Update issue status and assignees
Real-time Sync
Automatic synchronization of changes
Team Selection
Choose which Linear team to assign issues to
Project Assignment
Assign issues to specific projects
Card Setup Process
Automatic Installation
The Linear Issue Converter card is automatically installed when you connect your HubSpot portal.
Card Visibility
The card appears in the "Apps" tab of your HubSpot tickets, accessible to users with appropriate permissions.
User Permissions
Ensure your team members have access to the app and appropriate ticket permissions to use the card.
Step 6: Workflow Actions Setup
Set up automated Linear issue creation through HubSpot workflows for hands-free ticket processing.
Workflow Action Registration
Navigate to Workflow Setup
Go to the workflow setup page in your dashboard to register the custom action.
Register Action
Click "Register Action" to create the "Create Linear Issue" custom workflow action in your HubSpot account.
Create Workflow
In HubSpot, create a new workflow and add the "Create Linear Issue" action to automate issue creation.
Workflow Configuration
Recommended Workflow Setup
Trigger
"Ticket created" or "Ticket property changed"
Condition (Optional)
Filter by ticket category, priority, or other properties
Action
"Create Linear Issue" with configured title, description, and priority
Action Parameters
Configure the following parameters when setting up the workflow action:
| Parameter | Description | Example |
|---|---|---|
| Title | Issue title (can use ticket properties) | {{ticket.subject}} |
| Description | Issue description | {{ticket.content}} |
| Team | Linear team assignment | "Engineering" |
| Priority | Issue priority level | "High", "Medium", "Low" |
Step 7: Webhook Configuration
Enable real-time bidirectional synchronization between Linear and HubSpot using webhooks.
Webhook Benefits
Real-time Updates
Instant synchronization of changes
Bidirectional Sync
Changes sync both ways automatically
Comment Sync
Comments sync between platforms
Status Updates
Status changes sync automatically
Assignee Changes
Owner/assignee updates sync
Configurable
Choose what to sync
Webhook Setup Process
Enable in Settings
Go to Linear settings and enable webhook synchronization for your workspace.
Configure Sync Options
Choose which events to sync: status changes, comments, assignee updates, etc.
Test Synchronization
Make test changes in Linear to verify webhook synchronization is working correctly.
Supported Webhook Events
Linear → HubSpot
- • Issue status changes
- • Issue assignee updates
- • Issue comments
- • Issue priority changes
- • Issue label updates
HubSpot → Linear
- • Ticket status changes
- • Ticket owner updates
- • Ticket comments
- • Ticket priority changes
- • Ticket property updates
How to Use the Integration
Once configured, here's how to use the different features of the integration.
Using the App Card
Access the Card
Open any HubSpot ticket and navigate to the "Apps" tab to find the "Linear Issue Converter" card.
Create New Issue
Click "Create Linear Issue" to create a new issue. Fill in the title, description, select team, project, and priority.
Link Existing Issue
Use "Link Existing Issue" to search and connect an existing Linear issue to the current ticket.
Manage Issues
Update issue status, assignees, and view issue details directly from the HubSpot interface.
Using Workflow Actions
Automated Workflow
Once configured, workflow actions run automatically based on your triggers:
- • New tickets automatically create Linear issues
- • High-priority tickets create high-priority issues
- • Category-based routing to different Linear teams
- • Custom field mapping for specialized workflows
Using Webhook Synchronization
Automatic Synchronization
Webhook sync works automatically in the background:
- • Linear status changes update HubSpot tickets
- • HubSpot comments appear in Linear issues
- • Assignee changes sync between platforms
- • Priority and label updates stay in sync
Troubleshooting
Common issues and their solutions to help you get the most out of the integration.
Common Issues
Workspace Already Connected Error
Problem: You receive an error when trying to connect a Linear workspace.
Solution: Each Linear workspace can only be connected to one HubSpot portal. Check if the workspace is already connected to another portal, or disconnect it first.
App Card Not Visible
Problem: The Linear Issue Converter card doesn't appear in HubSpot tickets.
Solution: Ensure the app is properly installed and you have the necessary permissions. Check that you're looking in the "Apps" tab of the ticket.
Workflow Action Not Available
Problem: The "Create Linear Issue" action doesn't appear in HubSpot workflows.
Solution: Make sure you've registered the workflow action from the setup page and have the automation scope enabled in your HubSpot app.
Webhook Sync Not Working
Problem: Changes in Linear aren't syncing to HubSpot or vice versa.
Solution: Check that webhook synchronization is enabled in your Linear settings and that the webhook URLs are correctly configured.
Getting Help
Check Integration Status
Visit your dashboard to check the status of your connections and troubleshoot any issues.
Go to DashboardSupport & Resources
Additional resources to help you make the most of the Linear-HubSpot integration.
Support Channels
Ready to Connect Your HubSpot Account?
Join hundreds of teams already using Atlantic DevOps to streamline their workflows.