Linear Integration
Software project and bug tracking with Linear integration for CrewAI.
Overview
Enable your agents to manage issues, projects, and development workflows through Linear. Create and update issues, manage project timelines, organize teams, and streamline your software development process with AI-powered automation.
Prerequisites
Before using the Linear integration, ensure you have:
- A CrewAI Enterprise account with an active subscription
- A Linear account with appropriate workspace permissions
- Connected your Linear account through the Integrations page
Setting Up Linear Integration
1. Connect Your Linear Account
- Navigate to CrewAI Enterprise Integrations
- Find Linear in the Authentication Integrations section
- Click Connect and complete the OAuth flow
- Grant the necessary permissions for issue and project management
- Copy your Enterprise Token from Account Settings
2. Install Required Package
Available Actions
LINEAR_CREATE_ISSUE
LINEAR_CREATE_ISSUE
Description: Create a new issue in Linear.
Parameters:
teamId
(string, required): Team ID - Specify the Team ID of the parent for this new issue. Use Connect Portal Workflow Settings to allow users to select a Team ID. (example: “a70bdf0f-530a-4887-857d-46151b52b47c”).title
(string, required): Title - Specify a title for this issue.description
(string, optional): Description - Specify a description for this issue.statusId
(string, optional): Status - Specify the state or status of this issue.priority
(string, optional): Priority - Specify the priority of this issue as an integer.dueDate
(string, optional): Due Date - Specify the due date of this issue in ISO 8601 format.cycleId
(string, optional): Cycle ID - Specify the cycle associated with this issue.additionalFields
(object, optional): Additional Fields.
LINEAR_UPDATE_ISSUE
LINEAR_UPDATE_ISSUE
Description: Update an issue in Linear.
Parameters:
issueId
(string, required): Issue ID - Specify the Issue ID of the issue to update. (example: “90fbc706-18cd-42c9-ae66-6bd344cc8977”).title
(string, optional): Title - Specify a title for this issue.description
(string, optional): Description - Specify a description for this issue.statusId
(string, optional): Status - Specify the state or status of this issue.priority
(string, optional): Priority - Specify the priority of this issue as an integer.dueDate
(string, optional): Due Date - Specify the due date of this issue in ISO 8601 format.cycleId
(string, optional): Cycle ID - Specify the cycle associated with this issue.additionalFields
(object, optional): Additional Fields.
LINEAR_GET_ISSUE_BY_ID
LINEAR_GET_ISSUE_BY_ID
Description: Get an issue by ID in Linear.
Parameters:
issueId
(string, required): Issue ID - Specify the record ID of the issue to fetch. (example: “90fbc706-18cd-42c9-ae66-6bd344cc8977”).
LINEAR_GET_ISSUE_BY_ISSUE_IDENTIFIER
LINEAR_GET_ISSUE_BY_ISSUE_IDENTIFIER
Description: Get an issue by issue identifier in Linear.
Parameters:
externalId
(string, required): External ID - Specify the human-readable Issue identifier of the issue to fetch. (example: “ABC-1”).
LINEAR_SEARCH_ISSUE
LINEAR_SEARCH_ISSUE
Description: Search issues in Linear.
Parameters:
queryTerm
(string, required): Query Term - The search term to look for.issueFilterFormula
(object, optional): A filter in disjunctive normal form - OR of AND groups of single conditions.Available fields:title
,number
,project
,createdAt
Available operators:$stringExactlyMatches
,$stringDoesNotExactlyMatch
,$stringIsIn
,$stringIsNotIn
,$stringStartsWith
,$stringDoesNotStartWith
,$stringEndsWith
,$stringDoesNotEndWith
,$stringContains
,$stringDoesNotContain
,$stringGreaterThan
,$stringLessThan
,$numberGreaterThanOrEqualTo
,$numberLessThanOrEqualTo
,$numberGreaterThan
,$numberLessThan
,$dateTimeAfter
,$dateTimeBefore
LINEAR_DELETE_ISSUE
LINEAR_DELETE_ISSUE
Description: Delete an issue in Linear.
Parameters:
issueId
(string, required): Issue ID - Specify the record ID of the issue to delete. (example: “90fbc706-18cd-42c9-ae66-6bd344cc8977”).
LINEAR_ARCHIVE_ISSUE
LINEAR_ARCHIVE_ISSUE
Description: Archive an issue in Linear.
Parameters:
issueId
(string, required): Issue ID - Specify the record ID of the issue to archive. (example: “90fbc706-18cd-42c9-ae66-6bd344cc8977”).
LINEAR_CREATE_SUB_ISSUE
LINEAR_CREATE_SUB_ISSUE
Description: Create a sub-issue in Linear.
Parameters:
parentId
(string, required): Parent ID - Specify the Issue ID for the parent of this new issue.teamId
(string, required): Team ID - Specify the Team ID of the parent for this new sub-issue. Use Connect Portal Workflow Settings to allow users to select a Team ID. (example: “a70bdf0f-530a-4887-857d-46151b52b47c”).title
(string, required): Title - Specify a title for this issue.description
(string, optional): Description - Specify a description for this issue.additionalFields
(object, optional): Additional Fields.
LINEAR_CREATE_PROJECT
LINEAR_CREATE_PROJECT
Description: Create a new project in Linear.
Parameters:
teamIds
(object, required): Team ID - Specify the team ID(s) this project is associated with as a string or a JSON array. Use Connect Portal User Settings to allow your user to select a Team ID.projectName
(string, required): Project Name - Specify the name of the project. (example: “My Linear Project”).description
(string, optional): Project Description - Specify a description for this project.additionalFields
(object, optional): Additional Fields.
LINEAR_UPDATE_PROJECT
LINEAR_UPDATE_PROJECT
Description: Update a project in Linear.
Parameters:
projectId
(string, required): Project ID - Specify the ID of the project to update. (example: “a6634484-6061-4ac7-9739-7dc5e52c796b”).projectName
(string, optional): Project Name - Specify the name of the project to update. (example: “My Linear Project”).description
(string, optional): Project Description - Specify a description for this project.additionalFields
(object, optional): Additional Fields.
LINEAR_GET_PROJECT_BY_ID
LINEAR_GET_PROJECT_BY_ID
Description: Get a project by ID in Linear.
Parameters:
projectId
(string, required): Project ID - Specify the Project ID of the project to fetch. (example: “a6634484-6061-4ac7-9739-7dc5e52c796b”).
LINEAR_DELETE_PROJECT
LINEAR_DELETE_PROJECT
Description: Delete a project in Linear.
Parameters:
projectId
(string, required): Project ID - Specify the Project ID of the project to delete. (example: “a6634484-6061-4ac7-9739-7dc5e52c796b”).
LINEAR_SEARCH_TEAMS
LINEAR_SEARCH_TEAMS
Description: Search teams in Linear.
Parameters:
teamFilterFormula
(object, optional): A filter in disjunctive normal form - OR of AND groups of single conditions.Available fields:id
,name
Usage Examples
Basic Linear Agent Setup
Filtering Specific Linear Tools
Project and Team Management
Issue Hierarchy and Sub-task Management
Automated Development Workflow
Troubleshooting
Common Issues
Permission Errors
- Ensure your Linear account has necessary permissions for the target workspace
- Verify that the OAuth connection includes required scopes for Linear API
- Check if you have create/edit permissions for issues and projects in the workspace
Invalid IDs and References
- Double-check team IDs, issue IDs, and project IDs for correct UUID format
- Ensure referenced entities (teams, projects, cycles) exist and are accessible
- Verify that issue identifiers follow the correct format (e.g., “ABC-1”)
Team and Project Association Issues
- Use LINEAR_SEARCH_TEAMS to get valid team IDs before creating issues or projects
- Ensure teams exist and are active in your workspace
- Verify that team IDs are properly formatted as UUIDs
Issue Status and Priority Problems
- Check that status IDs reference valid workflow states for the team
- Ensure priority values are within the valid range for your Linear configuration
- Verify that custom fields and labels exist before referencing them
Date and Time Format Issues
- Use ISO 8601 format for due dates and timestamps
- Ensure time zones are handled correctly for due date calculations
- Verify that date values are valid and in the future for due dates
Search and Filter Issues
- Ensure search queries are properly formatted and not empty
- Use valid field names in filter formulas:
title
,number
,project
,createdAt
- Test simple filters before building complex multi-condition queries
- Verify that operator types match the data types of the fields being filtered
Sub-issue Creation Problems
- Ensure parent issue IDs are valid and accessible
- Verify that the team ID for sub-issues matches or is compatible with the parent issue’s team
- Check that parent issues are not already archived or deleted
Getting Help
Need Help?
Contact our support team for assistance with Linear integration setup or troubleshooting.