Linear

1. Overview

Linear is a modern project management tool designed specifically for software teams to track issues and coordinate development work. It provides a streamlined, fast, and intuitive interface that keeps teams focused on meaningful work.

Through GoInsight's Linear node, you can seamlessly integrate Linear operations into your automation workflows. You can manage issues in your Linear workspace, including creating, retrieving, updating, and deleting issues, as well as adding links to issues and managing their properties.

2. Prerequisites

• Before using this node, you need to have a valid Linear account.
• You need to configure API credentials with appropriate permissions to perform the desired operations on issues and teams.

3. Credentials

For detailed instructions on how to obtain and configure credentials, please refer to our official documentation: Credential Configuration Guide.

4. Supported Operations

Summary

This node primarily operates around issues in Linear.

Operation Details

Create an Issue

Creates a new issue in Linear using the GraphQL API. Returns the created issue's ID and title on success.

Input Parameters:

• Title: The title of the issue to be created. This will be displayed as the main heading of the issue. Keep it concise and descriptive. Example: "Fix login page redirect bug"
• TeamId: The unique identifier of the Linear team to which this issue belongs. You can obtain team IDs by: 1) Calling the Linear API's teams endpoint (GET /teams), 2) Checking your Linear workspace settings under Team Settings > General, 3) Using the List Teams action if available. The team ID is typically a UUID format string. Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Optional Parameters:

• Description: The detailed description of the issue in markdown format (optional). Supports standard markdown syntax including headers (# ## ###), bold (text), italic (text), links (text), code blocks (``code``), and lists (- item). Leave empty if no detailed description is needed. Example: "## Steps to reproduce

1. Go to login page
2. Enter credentials
3. Click submit

Expected: Redirect to dashboard

Actual: Stays on login page"

Output:

• Success (bool): Indicates whether the issue was created successfully. True if the issue was created, false if any error occurred during creation.
• IssueId (string): The unique identifier of the newly created issue. Use this ID to reference the issue in other Linear API calls (e.g., update, delete, or link operations). Empty if creation failed.
• IssueTitle (string): The title of the newly created issue, as confirmed by the Linear API. This should match the input Title parameter. Empty if creation failed.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream Linear API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging. 0=Request did not reach upstream API (network timeout or connection refused), 200=Request completed successfully, 4xx=Client error from upstream (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found), 5xx=Server error from upstream.
• StatusCode (number): Operation status code: 200=Request completed (check Success and ErrorMessage for actual result), -1=Parameter validation error (invalid or missing required parameters), 408=Request timeout, 500=Network or system error. Agent may retry on 408 or 500.
• ErrorMessage (string): Detailed error message if the operation failed, empty string when successful. When StatusCode is 200 and ErrorMessage is not empty, it indicates a business-level error from Linear API (e.g., invalid team ID, insufficient permissions). When StatusCode is -1, it describes which parameter is invalid and how to fix it. When StatusCode is 408 or 500, it describes the network or system error.

Get an Issue

Retrieves the details of a specified Linear issue by its ID using the GraphQL API.

Input Parameters:

• IssueId: The ID of the Linear issue to retrieve. Supports both formats:
• Short ID (recommended): Human-readable identifier like "LIN-123"
• UUID: Internal unique identifier like "8a7b9c1d-2e3f-4a5b-6c7d-8e9f0a1b2c3d"

You can obtain issue IDs from:

1. Linear issue URL (the part after /issue/, e.g., LIN-123)
2. Search Issues action
3. List Issues action

Example: "LIN-123"

Output:

• Success (bool): Indicates whether the issue was successfully retrieved.
• Issue (object): Detailed information of the issue:

id (string): The unique identifier of the issue.

title (string): The title of the issue.

description (string): The description of the issue in markdown format.

state (object): The current workflow state of the issue, including state name and type.

createdAt (string): ISO 8601 timestamp when the issue was created.

updatedAt (string): ISO 8601 timestamp when the issue was last updated.

priority (number): The priority of the issue (0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low).

assignee (object): The user assigned to the issue, including id and name.

team (object): The team the issue belongs to, including id and name.

labels (array): The labels attached to the issue.

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Many Issues

Retrieves multiple Linear issues for a specified team using the GraphQL API. Optionally include archived issues.

Optional Parameters:

• Limit: Number of issues to return per page. Valid range: 1-100. Recommended: 50 for balanced performance. Use smaller values (10-25) for initial testing or large issue objects. Example: 50
• After: Pagination cursor (an encoded string pointer to the next page). Leave empty for the first page. To fetch the next page, copy the 'endCursor' value from the previous response's PageInfo and paste it here. This is managed automatically by the API. Example: "eyJpZCI6IjEyMzQ1Njc4OTAifQ=="
• TeamId: Optional Team UUID to filter issues. Use the 'Get Teams' action to find this ID.

Output:

• Issues (object-array): List of issue objects. Each object contains:
• id (string): Unique issue identifier
• identifier (string): Human-readable identifier (e.g., 'TEAM-123')
• title (string): Issue title
• description (string): Issue description
• priority (number): Priority level (0=None, 1=Urgent, 2=High, 3=Medium, 4=Low)
• state (object): Contains 'name' (string) and 'type' (string: started/completed/canceled)
• assignee (object): Contains 'id', 'name', 'email' (may be null if unassigned)
• createdAt (string): ISO 8601 timestamp
• updatedAt (string): ISO 8601 timestamp
• PageInfo (object): Pagination information object:
• hasNextPage (boolean): Indicates if more pages exist
• endCursor (string): Cursor to use as 'After' parameter in next request. Pass this value to fetch the next page.
• StatusCode (number): Operation status code:
• 200: Success. The upstream API request completed successfully. Check ErrorMessage for business-level errors.
• -1: Parameter validation error. One or more input parameters are invalid or missing.
• 500: System error. Network timeout, connection failure, or response parsing error. The operation may be retried.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• 0: The request did not reach the upstream API (e.g., network timeout, connection refused).
• 200: Upstream API returned success.
• 400: Bad request (e.g., invalid GraphQL query).
• 401: Unauthorized (invalid or expired access token).
• 429: Rate limit exceeded.
• 5xx: Server error from upstream.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.
• When StatusCode is 200 and ErrorMessage is empty: Operation fully succeeded.
• When StatusCode is 200 and ErrorMessage is not empty: Upstream API returned a business error (e.g., GraphQL errors).
• When StatusCode is -1: Describes which parameter is invalid and how to fix it.
• When StatusCode is 500: Describes the system-level error (timeout, connection failure, etc.).

Update an Issue

Updates a specified Linear issue's fields such as title, description, state, priority, estimate, and due date using the GraphQL API.

Input Parameters:

• IssueId: The unique identifier of the issue to update. You can obtain this ID by using Get an Issue, Get Many Issues, or Search Issues actions. Example: "5842xxxxxxxxxxxx001"

Optional Parameters:

• Title: The new title for the issue, optional.
• Description: The new description in markdown format, optional.
• StateId: The new state ID for the issue (optional). States represent workflow stages like 'Backlog', 'In Progress', 'Done'. You can obtain state IDs by using the Get Workflow States action or from the Linear workspace settings. Example: "5842xxxxxxxxxxxx003"
• Priority: The new priority level for the issue (optional). Priority levels:
• 0: None (no priority set)
• 1: Urgent (critical, needs immediate attention)
• 2: High (important, high priority)
• 3: Medium (normal priority)
• 4: Low (can be addressed later)

Example: 1

• Estimate: The new time estimate in hours for the issue, optional.
• DueDate: The new due date in ISO 8601 format (optional). The format should be YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DD. Example: "2024-12-31" or "2024-12-31T23:59:59Z"

Output:

• Update (bool): Indicates whether the issue was successfully updated.
• Issue (object): The updated issue details including:

id (string): The issue ID.

title (string): The updated title.

description (string): The updated description in markdown format.

state (object): The issue's state with id (string) and name (string) properties.

priority (integer): The updated priority (0=None, 1=Urgent, 2=High, 3=Medium, 4=Low).

estimate (integer): The updated time estimate in hours.

dueDate (string): The updated due date in ISO 8601 format.

createdAt (string): The creation timestamp in ISO 8601 format.

updatedAt (string): The last update timestamp in ISO 8601 format.

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Delete an Issue

Deletes a Linear issue by its ID. Optionally, you can permanently delete the issue, skipping the 30-day grace period.

Input Parameters:

• IssueId: The ID of the Linear issue to delete. You can obtain this ID from the 'Get Many Issues' or 'Search Issues' actions. Example: 'ISS-123' or '01234567-89ab-cdef-0123-456789abcdef'

Optional Parameters:

• PermanentlyDelete: Whether to permanently delete the issue and bypass the 30-day grace period. If false (default), the issue will be soft-deleted and can be restored within 30 days. If true, the issue is permanently deleted immediately.

Output:

• Success (bool): Indicates whether the issue was deleted successfully. True when deletion succeeded, false otherwise.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (network timeout, connection failure).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. When StatusCode is 200 and ErrorMessage is not empty: API returned a business error (e.g., issue not found, permission denied).

Add a Link to an Issue

Adds an external link (attachment) to a specified Linear issue using the GraphQL API. The link will appear in the issue's Links section.

Input Parameters:

• IssueId: The internal ID (UUID format) of the target Linear issue. You can obtain this ID by calling 'Get an Issue' or 'Search Issues' actions.
• Url: The URL of the link to be added. Must be a valid URL starting with http:// or https://. Example: https://example.com/document
• Title: The display title for the link. This will be shown as the attachment name in Linear. Example: Design Document

Output:

• Attachment (object): The created attachment object containing: id (string, the unique identifier), title (string, the display title), url (string, the link URL), createdAt (string, ISO 8601 timestamp), issue (object, reference to parent issue).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

5. Example Usage

This section will guide you through creating a simple workflow to create an issue in Linear.

This example workflow consists of: Start -> [Linear Node] -> Answer.

Step-by-step Guide:

1. Add Tool Node:
   • In the workflow canvas, click the "+" button to add a new node.
   • In the popup panel, select the "Tools" tab.
   • Find and select "Linear" from the tool list.
   • From the supported operations for Linear, select "Create an Issue", which adds the corresponding node to the canvas.
2. Configure Node:
   • Click the "Create an Issue" node, and the configuration panel will appear on the right.
   • Credential Configuration: At the top of the panel, locate the credential field. Click the dropdown menu and select your configured Linear credential.
   • Parameter Filling: Fill in the required input parameters:
   • Title: Enter a descriptive title for the issue, for example, "Implement user authentication feature".
   • TeamId: Enter the unique identifier of the Linear team, for example, "a1b2c3d4-e5f6-7890-abcd-ef1234567890".
   • Description: (Optional) Enter a detailed description of the issue in markdown format, for example, "# User Auth Implementation\n\nThe system needs to support user registration and login functionality."
3. Run and Verify:
   • Once all required parameters are correctly filled in, error indicators will disappear from the workflow canvas.
   • Click the "Test Run" button at the top right of the canvas to execute the workflow.
   • After successful execution, you can click the log icon at the top right to view detailed input and output for the nodes, verifying that the operation was successful.

After completing these steps, your workflow will be ready. When you click "Test Run," a new issue will be created in your Linear workspace.

6. FAQs

Q: How do I find my Linear Team ID?

A: You can find your Team ID in several ways:

• Via Linear API's teams endpoint (GET /teams)
• In your Linear workspace settings under Team Settings > General
• Through the Get Teams action if available in your integration

Q: What happens when I delete an issue with PermanentlyDelete set to false?

A: When PermanentlyDelete is false (default), the issue will be soft-deleted and can be restored within a 30-day grace period. If set to true, the issue is permanently deleted immediately.

Q: How do I update an issue's workflow state?

A: To update an issue's state, you need to provide the StateId parameter in the Update an Issue action. You can obtain valid state IDs by using the Get Workflow States action or by checking your Linear workspace settings for the workflow states.

7. Official Documentation

Linear Official API Documentation