> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/linear.md).

# Linear

Connect to Linear to manage issues and projects

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector | Authentication |
| --------- | -------------- |
| Linear    | OAuth sign-in  |

#### Linear

Connect to Linear to access your projects, issues, and workflows.

**Set up in Linear**

1. When the Linear authorization window opens, sign in to your Linear account.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Linear**.
2. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

StackAI obtains the OAuth credentials during sign-in. You do not need to paste an access token or refresh token.

**Provider documentation:** [Setup reference](https://developers.linear.app/docs/oauth/authentication).

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

#### Detailed setup guides

* [Connect Linear](https://docs.stackai.com/integrations/catalog/linear/connect-linear.md)

## Use an action

1. Add the required **Linear** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Create Issue

Create a new issue in Linear with title, description, assignee, and other properties.

**Inputs**

| Field       | Type            | Required | Description                                                                                 |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------- |
| Team        | select (string) | Yes      | Select the team where the issue will be created. Options load from the selected connection. |
| Title       | string          | Yes      | Enter the title of the issue.                                                               |
| Description | string          | No       | Enter the description of the issue (supports markdown).                                     |
| Assignee ID | string          | No       | Select a user to assign this issue to (optional).                                           |
| State ID    | string          | No       | Select the initial state for this issue (optional).                                         |
| Priority    | integer         | No       | Set the priority level (0-4, where 0=No priority, 1=Urgent, 4=Low).                         |
| Project ID  | string          | No       | Select a project to add this issue to (optional).                                           |

**Outputs**

| Field            | Type    | Description                                          |
| ---------------- | ------- | ---------------------------------------------------- |
| Success          | boolean | Indicates if the operation was successful.           |
| Issue ID         | string  | The unique identifier of the created issue.          |
| Issue URL        | string  | Direct link to the created issue.                    |
| Issue Identifier | string  | The team prefix and number identifier for the issue. |

#### Get Issue

Get detailed information about a specific Linear issue.

**Inputs**

| Field    | Type   | Required | Description                                |
| -------- | ------ | -------- | ------------------------------------------ |
| Issue ID | string | Yes      | Enter the ID of the issue you want to get. |

**Outputs**

| Field            | Type    | Description                                          |
| ---------------- | ------- | ---------------------------------------------------- |
| Issue ID         | string  | The unique identifier of the issue.                  |
| Issue Identifier | string  | The team prefix and number identifier for the issue. |
| Title            | string  | The title of the issue.                              |
| Description      | string  | The description of the issue.                        |
| Status           | string  | The current workflow status of the issue.            |
| Status Category  | string  | The standardized category of the workflow state.     |
| Assignee Name    | string  | The person currently assigned to this issue.         |
| Team Name        | string  | The team that owns this issue.                       |
| Priority         | integer | The priority level of the issue.                     |
| Issue URL        | string  | Direct link to view the issue.                       |
| Created At       | string  | The date and time the issue was created.             |
| Updated At       | string  | The date and time the issue was last updated.        |

#### Update Issue

Update an existing issue in Linear. Can modify title, description, assignee, state, priority, or project.

**Inputs**

| Field       | Type    | Required | Description                                                            |
| ----------- | ------- | -------- | ---------------------------------------------------------------------- |
| Issue ID    | string  | Yes      | Enter the ID of the issue you want to update.                          |
| Title       | string  | No       | Update the title of the issue (optional).                              |
| Description | string  | No       | Update the description of the issue (supports markdown).               |
| Assignee ID | string  | No       | Change the assignee of this issue (optional).                          |
| State ID    | string  | No       | Change the state of this issue (optional).                             |
| Priority    | integer | No       | Update the priority level (0-4, where 0=No priority, 1=Urgent, 4=Low). |
| Project ID  | string  | No       | Move this issue to a different project (optional).                     |

**Outputs**

| Field            | Type    | Description                                          |
| ---------------- | ------- | ---------------------------------------------------- |
| Success          | boolean | Indicates if the operation was successful.           |
| Issue ID         | string  | The unique identifier of the updated issue.          |
| Issue URL        | string  | Direct link to the updated issue.                    |
| Issue Identifier | string  | The team prefix and number identifier for the issue. |
| Status           | string  | The current workflow status of the issue.            |
| Status Category  | string  | The standardized category of the workflow state.     |

#### Search Issues

Search for Linear issues using various filters like team, assignee, state, project, or text search.

**Inputs**

| Field        | Type            | Required | Description                                                                                    |
| ------------ | --------------- | -------- | ---------------------------------------------------------------------------------------------- |
| Search Query | string          | No       | Enter search terms to find issues.                                                             |
| Team         | select (string) | No       | Select a specific team to filter issues (optional). Options load from the selected connection. |
| Assignee ID  | string          | No       | Select a specific assignee to filter issues (optional).                                        |
| State ID     | string          | No       | Select a specific state to filter issues (optional).                                           |
| Project ID   | string          | No       | Select a specific project to filter issues (optional).                                         |

**Outputs**

| Field         | Type    | Description                                    |
| ------------- | ------- | ---------------------------------------------- |
| Issues        | object  | Found issues matching your search.             |
| Total Count   | integer | Total number of issues that match the search.  |
| Has Next Page | boolean | Indicates if there are more results available. |

#### Create Comment

Add a comment to a Linear issue.

**Inputs**

| Field        | Type   | Required | Description                                            |
| ------------ | ------ | -------- | ------------------------------------------------------ |
| Issue ID     | string | Yes      | Enter the ID of the issue you want to comment on.      |
| Comment Body | string | Yes      | Enter the content of your comment (supports markdown). |

**Outputs**

| Field            | Type    | Description                                         |
| ---------------- | ------- | --------------------------------------------------- |
| Success          | boolean | Indicates if the operation was successful.          |
| Comment ID       | string  | The unique identifier of the created comment.       |
| Comment URL      | string  | Direct link to view the created comment.            |
| Issue Identifier | string  | The issue identifier where the comment was created. |
| Created At       | string  | The date and time the comment was created.          |

#### Get Issue Comments

Get all comments on a Linear issue with details about authors and timestamps.

**Inputs**

| Field    | Type   | Required | Description                                                                                    |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| Issue ID | string | Yes      | Enter the issue ID (e.g., ENG-123). Use 'Search Issues' action to find available issues first. |

**Outputs**

| Field            | Type    | Description                                   |
| ---------------- | ------- | --------------------------------------------- |
| Issue ID         | string  | The issue these comments belong to.           |
| Issue Identifier | string  | The issue identifier.                         |
| Issue Title      | string  | The title of the issue.                       |
| Comments         | object  | All comments on this issue.                   |
| Total Count      | integer | Total number of comments available.           |
| Has Next Page    | boolean | Indicates if there are more comments to load. |

#### List Teams

Get a list of all teams in your Linear workspace with their details and statistics.

**Inputs**

No input fields are required in this catalog entry.

**Outputs**

| Field       | Type    | Description                         |
| ----------- | ------- | ----------------------------------- |
| Teams       | object  | All teams in your Linear workspace. |
| Total Count | integer | Total number of teams available.    |

#### List Users

Get a list of all users in your Linear workspace with their details and permissions.

**Inputs**

| Field                  | Type    | Required | Description                                         |
| ---------------------- | ------- | -------- | --------------------------------------------------- |
| Include Disabled Users | boolean | No       | Include inactive users in the list. Default: false. |

**Outputs**

| Field       | Type    | Description                         |
| ----------- | ------- | ----------------------------------- |
| Users       | object  | All users in your Linear workspace. |
| Total Count | integer | Total number of users available.    |

#### List Workflow States

Get a list of workflow states for teams in your Linear workspace. Filter by team or get all states.

**Inputs**

| Field | Type            | Required | Description                                                                                                                  |
| ----- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Team  | select (string) | No       | Select a team to get its workflow states (optional - shows all if not specified). Options load from the selected connection. |

**Outputs**

| Field           | Type    | Description                                |
| --------------- | ------- | ------------------------------------------ |
| Workflow States | object  | Available workflow states for issues.      |
| Total Count     | integer | Total number of workflow states available. |

#### List Projects

Get a list of projects in your Linear workspace with their details, progress, and statistics.

**Inputs**

| Field                      | Type            | Required | Description                                                                                                          |
| -------------------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| Include Completed Projects | boolean         | No       | Include completed projects in the list. Default: true.                                                               |
| Team                       | select (string) | No       | Select a team to filter projects (optional - shows all if not specified). Options load from the selected connection. |

**Outputs**

| Field         | Type    | Description                                   |
| ------------- | ------- | --------------------------------------------- |
| Projects      | object  | All projects in your Linear workspace.        |
| Total Count   | integer | Total number of projects available.           |
| Has Next Page | boolean | Indicates if there are more projects to load. |

### Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

#### On Issue Created

Starts when an issue is created in the selected Linear team.

1. In Linear, open **Settings** -> **API** -> **New webhook**. 2. Paste your StackAI webhook URL: {{webhook\_url}} 3. Under **Data change events**, tick **Issues**. Leave the rest unticked so Linear does not deliver events this trigger will only discard. 4. Leave the scope as **All public teams** and create the webhook. This trigger filters by team itself, so you can change the **Team** below without touching Linear. If the team is private, scope the webhook to that team instead, and recreate it if you change the Team here. 5. Open the webhook you just created, copy its **signing secret**, and paste it into **Webhook Signing Secret** below. Every delivery whose signature does not match is rejected, so the trigger will never fire without it. 6. Publish this workflow. Each issue created in that team now starts a run. Creating a webhook needs Linear workspace admin rights, which is why StackAI cannot do it for you. If you are not an admin, ask one to do steps 1 to 4 and send you the secret.

**Configuration**

| Field                  | Type                      | Required | Description                                                                                                                                   |
| ---------------------- | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Team                   | select (string)           | Yes      | Only start for issues in this team. Options load from the selected connection.                                                                |
| Labels                 | multiple\_select (string) | No       | Only start for issues carrying at least one of these labels. Leave empty for any label. Options load from the selected connection.            |
| Workflow States        | multiple\_select (string) | No       | Only start for issues in one of these states. Leave empty for any state. Options load from the selected connection.                           |
| Webhook Signing Secret | secret                    | Yes      | The signing secret from the Linear webhook you pointed at this trigger's URL. Every delivery is rejected unless it is signed with this value. |

**Event inputs**

| Field           | Type    | Required | Description                                                               |
| --------------- | ------- | -------- | ------------------------------------------------------------------------- |
| Issue ID        | string  | Yes      | The issue's UUID, for passing to other Linear actions.                    |
| Identifier      | string  | Yes      | The human-readable issue key.                                             |
| Title           | string  | Yes      | The issue title.                                                          |
| Description     | string  | No       | The issue description, as Markdown.                                       |
| Status          | string  | No       | The workflow state name.                                                  |
| Status Category | string  | No       | The state's category: backlog, unstarted, started, completed or canceled. |
| Assignee        | string  | No       | The assignee's name, empty when the issue is unassigned.                  |
| Team            | string  | No       | The team the issue belongs to.                                            |
| Labels          | array   | Yes      | The issue's label names. Default: \[].                                    |
| Priority        | integer | No       | Linear's priority number: 0 none, 1 urgent, 2 high, 3 medium, 4 low.      |
| Issue URL       | string  | No       | Link to the issue in Linear.                                              |
| Created At      | string  | No       | When the issue was created.                                               |
| Updated At      | string  | No       | When the issue was last updated.                                          |

**Outputs**

| Field           | Type          | Description                                                               |
| --------------- | ------------- | ------------------------------------------------------------------------- |
| Issue ID        | string        | The issue's UUID, for passing to other Linear actions.                    |
| Identifier      | string        | The human-readable issue key.                                             |
| Title           | string        | The issue title.                                                          |
| Description     | string        | The issue description, as Markdown.                                       |
| Status          | string        | The workflow state name.                                                  |
| Status Category | string        | The state's category: backlog, unstarted, started, completed or canceled. |
| Assignee        | string        | The assignee's name, empty when the issue is unassigned.                  |
| Team            | string        | The team the issue belongs to.                                            |
| Labels          | string\_array | The issue's label names.                                                  |
| Priority        | integer       | Linear's priority number: 0 none, 1 urgent, 2 high, 3 medium, 4 low.      |
| Issue URL       | string        | Link to the issue in Linear.                                              |
| Created At      | string        | When the issue was created.                                               |
| Updated At      | string        | When the issue was last updated.                                          |

### Important behavior

If an operation is denied, check the connection’s granted permissions and the account’s access in the provider. Reauthorize the connection when it needs additional permissions.

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/linear.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
