---
title: Linear
description: "Streamline your project and issue tracking"
---

<Snippet file="integration-getting-started.mdx" />

## Installation

To get started with the Linear integration on Trigger.dev, you need to install the `@trigger.dev/linear` package.
You can do this using npm, pnpm, or yarn:

<CodeGroup>

```bash npm
npm install @trigger.dev/linear@latest
```

```bash pnpm
pnpm add @trigger.dev/linear@latest
```

```bash yarn
yarn add @trigger.dev/linear@latest
```

</CodeGroup>

## Authentication

To use the Linear API with Trigger.dev, you can either use OAuth or a Personal API Key.

### OAuth

```ts
import { Linear } from "@trigger.dev/linear";

//this will use OAuth
const linear = new Linear({
  id: "linear",
});
```

### Personal API Key

You can create a Personal API Key in your [Linear API Settings](https://linear.app/settings/api).

```ts
import { Linear } from "@trigger.dev/linear";

//this will use the passed in API key (defined in your environment variables)
const linear = new Linear({
  id: "linear",
  apiKey: process.env["LINEAR_API_KEY"],
});
```

## Usage

Include the Linear integration in your Trigger.dev job.

```ts
client.defineJob({
  id: "linear-new-issue-autoresponder",
  name: "Linear - New Issue Autoresponder",
  version: "0.1.0",
  integrations: {
    //use the linear integration
    linear,
  },
  //trigger on issue created events
  trigger: linear.onIssueCreated(),
  run: async (payload, io, ctx) => {
    //get new issue ID from the event payload
    const newIssueId = payload.data.id;

    //comment
    await io.linear.createComment("create-comment", {
      issueId: newIssueId,
      body: "Thank's for opening this issue!",
    });

    //react
    await io.linear.createReaction("create-reaction", {
      issueId: newIssueId,
      emoji: "+1",
    });

    //store and display in the job run
    return { payload, ctx };
  },
});
```

### Serialization helper

Use the `serializeLinearOutput` helper instead of returning raw Linear SDK responses:

```ts
import { Linear, serializeLinearOutput } from "@trigger.dev/linear";
...
client.defineJob({
  id: "linear-sdk",
  name: "Linear SDK",
  version: "0.1.0",
  integrations: {
    linear,
  },
  trigger: eventTrigger({
    name: "linear.sdk",
  }),
  run: async (payload, io, ctx) => {
    //the official Linear SDK is exposed as `client`
    const issues = await io.linear.runTask("first-two", async (client) => {
      //these nodes contain values we can't serialize, e.g. functions
      const { nodes } = await client.issues({ first: 2 });
      //we remove them with this little helper
      return serializeLinearOutput(nodes);
    });
    return issues;
  },
});
```

### Pagination

You can paginate responses two different ways:

1. Iterating the same integration task with different params
2. Using the `getAll` helper exposed on the integration (**recommended!**)

_When ordering results, make sure to use the `PaginationOrderBy` enum._

```ts
import { Linear, PaginationOrderBy, serializeLinearOutput } from "@trigger.dev/linear";
...
client.defineJob({
  id: "linear-pagination",
  name: "Linear Pagination",
  version: "0.1.0",
  integrations: {
    linear,
  },
  trigger: eventTrigger({
    name: "linear.paginate",
  }),
  run: async (payload, io, ctx) => {
    //the same params will be used for all tasks
    const params = { first: 5, orderBy: PaginationOrderBy.UpdatedAt };

    //1. Linear integration - no pagination helper
    let edges = await io.linear.issues("get-issues", params);
    let noHelper = edges.nodes;

    for (let i = 0; edges.pageInfo.hasNextPage; i++) {
      edges = await io.linear.issues(`get-more-issues-${i}`, {
        ...params,
        after: edges.pageInfo.endCursor,
      });
      noHelper = noHelper.concat(edges.nodes);
    }

    //2. Linear integration - with the pagination helper
    const withHelper = await io.linear.getAll(io.linear.issues, "get-all", params);

    return {
      issueCounts: {
        withSdk: sdkIssues.length,
        noHelper: noHelper.length,
        withHelper: withHelper.length,
      },
    };
  },
});
```

## Triggers

### Attachments

| Function Name         | Description                                    |
| --------------------- | ---------------------------------------------- |
| `onAttachment`        | When any action is performed on an attachment. |
| `onAttachmentCreated` | When an attachment is created.                 |
| `onAttachmentRemoved` | When an attachment is removed.                 |
| `onAttachmentUpdated` | When an attachment is updated.                 |

### Comments

| Function Name      | Description                                 |
| ------------------ | ------------------------------------------- |
| `onComment`        | When any action is performed on an comment. |
| `onCommentCreated` | When an comment is created.                 |
| `onCommentRemoved` | When an comment is removed.                 |
| `onCommentUpdated` | When an comment is updated.                 |

### Cycles

| Function Name    | Description                               |
| ---------------- | ----------------------------------------- |
| `onCycle`        | When any action is performed on an cycle. |
| `onCycleCreated` | When an cycle is created.                 |
| `onCycleRemoved` | When an cycle is removed.                 |
| `onCycleUpdated` | When an cycle is updated.                 |

### Issues

| Function Name    | Description                               |
| ---------------- | ----------------------------------------- |
| `onIssue`        | When any action is performed on an issue. |
| `onIssueCreated` | When an issue is created.                 |
| `onIssueRemoved` | When an issue is removed.                 |
| `onIssueUpdated` | When an issue is updated.                 |

### Issue Labels

| Function Name         | Description                                     |
| --------------------- | ----------------------------------------------- |
| `onIssueLabel`        | When any action is performed on an issue label. |
| `onIssueLabelCreated` | When an issue label is created.                 |
| `onIssueLabelRemoved` | When an issue label is removed.                 |
| `onIssueLabelUpdated` | When an issue label is updated.                 |

### Issue SLAs

| Function Name        | Description                                   |
| -------------------- | --------------------------------------------- |
| `onIssueSLA`         | When any action is performed on an issue SLA. |
| `onIssueSLASet`      | When an issue SLA is set.                     |
| `onIssueSLABreached` | When an issue SLA is breached.                |
| `onIssueSLAHighRisk` | When an issue SLA is high risk.               |

### Projects

| Function Name      | Description                                 |
| ------------------ | ------------------------------------------- |
| `onProject`        | When any action is performed on an project. |
| `onProjectCreated` | When an project is created.                 |
| `onProjectRemoved` | When an project is removed.                 |
| `onProjectUpdated` | When an project is updated.                 |

### Project Updates

| Function Name            | Description                                        |
| ------------------------ | -------------------------------------------------- |
| `onProjectUpdate`        | When any action is performed on an project update. |
| `onProjectUpdateCreated` | When an project update is created.                 |
| `onProjectUpdateRemoved` | When an project update is removed.                 |
| `onProjectUpdateUpdated` | When an project update is updated.                 |

### Reactions

| Function Name       | Description                                  |
| ------------------- | -------------------------------------------- |
| `onReaction`        | When any action is performed on an reaction. |
| `onReactionCreated` | When an reaction is created.                 |
| `onReactionRemoved` | When an reaction is removed.                 |
| `onReactionUpdated` | When an reaction is updated.                 |

## Tasks

### Attachments

| Function Name      | Description                |
| ------------------ | -------------------------- |
| `attachment`       | Gets an attachment.        |
| `attachments`      | Gets multiple attachments. |
| `createAttachment` | Creates an attachment.     |
| `deleteAttachment` | Deletes an attachment.     |
| `updateAttachment` | Updates an attachment.     |

### Attachment Links

| Function Name             | Description                                |
| ------------------------- | ------------------------------------------ |
| `attachmentLinkFront`     | Links a Front conversation to an issue.    |
| `attachmentLinkIntercom`  | Links a Intercom conversation to an issue. |
| `attachmentLinkJiraIssue` | Links a Jira issue to an issue.            |
| `attachmentLinkSlack`     | Links a Slack message to an issue.         |
| `attachmentLinkURL`       | Links any URL to an issue.                 |
| `attachmentLinkZendesk`   | Links a Zendesk ticket to an issue.        |

### Comments

| Function Name   | Description             |
| --------------- | ----------------------- |
| `comment`       | Gets a comment.         |
| `comments`      | Gets multiple comments. |
| `createComment` | Creates a comment.      |
| `deleteComment` | Deletes a comment.      |
| `updateComment` | Updates a comment.      |

### Cycles

| Function Name  | Description       |
| -------------- | ----------------- |
| `archiveCycle` | Archives a cycle. |
| `createCycle`  | Creates a cycle.  |
| `updateCycle`  | Updates a cycle.  |

### Documents

| Function Name     | Description              |
| ----------------- | ------------------------ |
| `document`        | Gets a document.         |
| `documents`       | Gets multiple documents. |
| `createDocument`  | Creates a document.      |
| `searchDocuments` | Searches documents.      |

### Favorites

| Function Name    | Description              |
| ---------------- | ------------------------ |
| `favorite`       | Gets a favorite.         |
| `favorites`      | Gets multiple favorites. |
| `createFavorite` | Creates a favorite.      |

### Issues

| Function Name  | Description           |
| -------------- | --------------------- |
| `issue`        | Gets an issue.        |
| `issues`       | Gets multiple issues. |
| `archiveIssue` | Archives an issue.    |
| `createIssue`  | Creates an issue.     |
| `deleteIssue`  | Deletes an issue.     |
| `searchIssues` | Searches issues.      |
| `updateIssue`  | Updates an issue.     |

### Issue Labels

| Function Name      | Description                 |
| ------------------ | --------------------------- |
| `issueLabel`       | Gets an issue label.        |
| `issueLabels`      | Gets multiple issue labels. |
| `createIssueLabel` | Creates an issue label.     |
| `deleteIssueLabel` | Deletes an issue label.     |
| `updateIssueLabel` | Updates an issue label.     |

### Issue Relations

| Function Name         | Description                    |
| --------------------- | ------------------------------ |
| `issueRelation`       | Gets an issue relation.        |
| `issueRelations`      | Gets multiple issue relations. |
| `createIssueRelation` | Creates an issue relation.     |

### Notifications

| Function Name                    | Description                          |
| -------------------------------- | ------------------------------------ |
| `notification`                   | Gets a notification.                 |
| `notifications`                  | Gets multiple notifications.         |
| `archiveNotification`            | Archives a notification.             |
| `createNotificationSubscription` | Creates a notification subscription. |

### Organizations

| Function Name                      | Description                     |
| ---------------------------------- | ------------------------------- |
| `organization`                     | Gets the viewer's organization. |
| `createOrganizationFromOnboarding` | Creates an organization.        |
| `createOrganizationInvite`         | Creates an organization invite. |

### Projects

| Function Name    | Description             |
| ---------------- | ----------------------- |
| `project`        | Gets a project.         |
| `projects`       | Gets multiple projects. |
| `archiveProject` | Archives a project.     |
| `createProject`  | Creates a project.      |
| `deleteProject`  | Deletes a project.      |
| `searchProjects` | Searches projects.      |
| `updateProject`  | Updates a project.      |

### Project Links

| Function Name       | Description                  |
| ------------------- | ---------------------------- |
| `projectLink`       | Gets a project link.         |
| `projectLinks`      | Gets multiple project links. |
| `createProjectLink` | Creates a project link.      |

### Project Updates

| Function Name         | Description                    |
| --------------------- | ------------------------------ |
| `projectUpdate`       | Gets a project update.         |
| `projectUpdates`      | Gets multiple project updates. |
| `createProjectUpdate` | Creates a project update.      |
| `deleteProjectUpdate` | Deletes a project update.      |
| `updateProjectUpdate` | Updates a project update.      |

### Reactions

| Function Name    | Description         |
| ---------------- | ------------------- |
| `createReaction` | Creates a reaction. |
| `deleteReaction` | Deletes a reaction. |

### Roadmaps

| Function Name    | Description         |
| ---------------- | ------------------- |
| `archiveRoadmap` | Archives a roadmap. |
| `createRoadmap`  | Creates a roadmap.  |

### Teams

| Function Name | Description          |
| ------------- | -------------------- |
| `team`        | Gets a team.         |
| `teams`       | Gets multiple teams. |
| `createTeam`  | Creates a team.      |

### Team Memberships

| Function Name          | Description                     |
| ---------------------- | ------------------------------- |
| `teamMembership`       | Gets a team membership.         |
| `teamMemberships`      | Gets multiple team memberships. |
| `createTeamMembership` | Creates a team membership.      |

### Templates

| Function Name | Description              |
| ------------- | ------------------------ |
| `template`    | Gets a template.         |
| `templates`   | Gets multiple templates. |

### Users

| Function Name | Description          |
| ------------- | -------------------- |
| `user`        | Gets a user.         |
| `users`       | Gets multiple users. |
| `updateUser`  | Updates a user.      |

### Webhooks

| Function Name   | Description             |
| --------------- | ----------------------- |
| `webhook`       | Gets a webhook.         |
| `webhooks`      | Gets multiple webhooks. |
| `createWebhook` | Creates a webhook.      |
| `deleteWebhook` | Deletes a webhook.      |
| `updateWebhook` | Updates a webhook.      |

### Workflow States

| Function Name          | Description                    |
| ---------------------- | ------------------------------ |
| `workflowState`        | Gets a workflow state.         |
| `workflowStates`       | Gets multiple workflow states. |
| `archiveWorkflowState` | Archives a workflow state.     |
| `createWorkflowState`  | Creates a workflow state.      |

### Misc

| Function Name            | Description                            |
| ------------------------ | -------------------------------------- |
| `createProjectMilestone` | Creates a project milestone.           |
| `issuePriorityValues`    | Gets issue priority values and labels. |
| `viewer`                 | Gets the currently authenticated user. |

## Example jobs

<Card title="Code examples" icon="code" href="https://trigger.dev/apis/linear">
  Check out pre-built jobs using Linear in our API section.
</Card>
