---
url: https://salimhamed.github.io/jigs/api/steps/linear.md
---
# steps/linear

Read and update Linear issues outside workflow code.

Wrap steps in a factory-owned `"use step"` file. Never call them directly from a workflow.

## Interfaces

### CreateIssueInProjectInput

Fields used to create a Linear ticket in a project's first team.

#### Properties

| Property | Type |
| :------ | :------ |
|  `description` | `string` |
|  `project` | `string` |
|  `title` | `string` |

***

### LinearIssueMatch

A matching Linear ticket returned by a project title search.

#### Properties

| Property | Type |
| :------ | :------ |
|  `description` | `string` |
|  `id` | `string` |
|  `identifier` | `string` |
|  `state` | `string` |
|  `title` | `string` |
|  `url` | `string` |

***

### TicketStatusResult

The before-and-after state names from a ticket status update.

#### Properties

| Property | Type |
| :------ | :------ |
|  `changed` | `boolean` |
|  `from` | `string` |
|  `to` | `string` |

## Type Aliases

### NeedsHumanContext

```ts
type NeedsHumanContext = object;
```

What the comment's footer says about the run that posted it. The factory's
step wrapper builds it: the run id and the workflow name come from the
Workflow SDK's metadata, and the dashboard link from the service's own
configuration — none of it visible to the workflow. Where the run paused is the
halt's, not the context's: only the routine that raised it knows.

#### Properties

| Property | Type |
| :------ | :------ |
|  `dashboardUrl?` | `string` |
|  `runId` | `string` |
|  `workflow?` | `string` |

***

### RenderNeedsHumanComment()

```ts
type RenderNeedsHumanComment = (halt, context, participants) => string;
```

Renders the Linear comment that asks a person to unblock a run.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `halt` | [`Halt`](../jigs.md#halt) |
| `context` | [`NeedsHumanContext`](#needshumancontext) |
| `participants` | [`TicketParticipants`](#ticketparticipants) |

#### Returns

`string`

***

### RenderTicketNote()

```ts
type RenderTicketNote = (note, participants) => string;
```

Renders a non-blocking Linear note for ticket participants.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `note` | [`TicketNote`](../jigs.md#ticketnote) |
| `participants` | [`TicketParticipants`](#ticketparticipants) |

#### Returns

`string`

***

### TicketParticipants

```ts
type TicketParticipants = object;
```

Who the comment greets. Either may be absent, and they are often the same.

#### Properties

| Property | Type |
| :------ | :------ |
|  `assignee` | `LinearUser` | `null` |
|  `creator` | `LinearUser` | `null` |

## Variables

### checkForTicketHumanReply

```ts
const checkForTicketHumanReply: CheckForTicketHumanReply;
```

Look for a reply since the last check, excluding every comment the run posted.

***

### renderNeedsHumanComment

```ts
const renderNeedsHumanComment: RenderNeedsHumanComment;
```

Render the default human-input request as Linear Markdown.

***

### renderTicketNote

```ts
const renderTicketNote: RenderTicketNote;
```

Render the default non-blocking ticket note as Linear Markdown.

## Functions

### createComment()

```ts
function createComment(issueId, body): Promise<{
  createdAt: string;
  id: string;
}>;
```

Post a comment on a ticket.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `issueId` | `string` |
| `body` | `string` |

#### Returns

`Promise`<{
`createdAt`: `string`;
`id`: `string`;
}>

***

### createIssueInProject()

```ts
function createIssueInProject(input): Promise<{
  id: string;
  identifier: string;
  url: string;
}>;
```

Create a ticket in the project’s first team.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `input` | [`CreateIssueInProjectInput`](#createissueinprojectinput) |

#### Returns

`Promise`<{
`id`: `string`;
`identifier`: `string`;
`url`: `string`;
}>

***

### fetchTicketSnapshot()

```ts
function fetchTicketSnapshot(issueId): Promise<TicketSnapshot>;
```

Read the ticket’s current details and discussion.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `issueId` | `string` |

#### Returns

`Promise`<[`TicketSnapshot`](../jigs.md#ticketsnapshot)>

***

### findIssueInProject()

```ts
function findIssueInProject(input): Promise<LinearIssueMatch | null>;
```

Find the newest ticket in a project whose title starts with the given text.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `input` | { `project`: `string`; `titlePrefix`: `string`; } |
| `input.project` | `string` |
| `input.titlePrefix` | `string` |

#### Returns

`Promise`<[`LinearIssueMatch`](#linearissuematch) | `null`>

***

### postTicketHumanInputRequest()

```ts
function postTicketHumanInputRequest(
   issueId, 
   halt, 
   metadata, 
   render): Promise<{
  commentId: string;
  postedAt: string;
}>;
```

Post a question or failure on the ticket so a person can help the run continue.

#### Parameters

| Parameter | Type | Default value |
| :------ | :------ | :------ |
| `issueId` | `string` | `undefined` |
| `halt` | [`Halt`](../jigs.md#halt) | `undefined` |
| `metadata` | `NamedRunMetadata` | `undefined` |
| `render` | [`RenderNeedsHumanComment`](#renderneedshumancomment) | `renderNeedsHumanComment` |

#### Returns

`Promise`<{
`commentId`: `string`;
`postedAt`: `string`;
}>

***

### postTicketNote()

```ts
function postTicketNote(
   issueId, 
   note, 
   render): Promise<{
  commentId: string;
}>;
```

Tell ticket participants something the run decided, without waiting for a reply.

#### Parameters

| Parameter | Type | Default value |
| :------ | :------ | :------ |
| `issueId` | `string` | `undefined` |
| `note` | [`TicketNote`](../jigs.md#ticketnote) | `undefined` |
| `render` | [`RenderTicketNote`](#renderticketnote) | `renderTicketNote` |

#### Returns

`Promise`<{
`commentId`: `string`;
}>

***

### resolveLinearIssue()

```ts
function resolveLinearIssue(reference): Promise<LinearIssueRef>;
```

Resolve a Linear identifier or issue ID before claiming or reading the ticket.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `reference` | `string` |

#### Returns

`Promise`<`LinearIssueRef`>

***

### setTicketStatus()

```ts
function setTicketStatus(issueId, stateName): Promise<TicketStatusResult>;
```

Set a ticket to one of its team's named states.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `issueId` | `string` |
| `stateName` | `string` |

#### Returns

`Promise`<[`TicketStatusResult`](#ticketstatusresult)>