> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jinba.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear

> Manage Linear issues, teams, and project progress

## Overview

The Linear tools connect to the Linear GraphQL API so your workflows can create and update issues, add comments, look up teams, and track project progress.

## Key Features

* `LINEAR_CREATE_ISSUE`
  * Create a new issue in a Linear team.
  * Key inputs: `team_id` (required), `title` (required), `description` (Markdown), `state_id`, `assignee_id`, `project_id`, `label_ids`, `subscriber_ids`, `priority` (integer 0–4), `estimate` (integer ≥ 0).
* `LINEAR_GET_ISSUES`
  * Retrieve a list of issues with optional server-side filters.
  * Key inputs: `team_id`, `state_id`, `assignee_id`, `project_id`, `label_ids` (matches issues containing any of the given labels), `updated_after` / `updated_before` (ISO 8601, e.g. `2024-01-01T00:00:00Z`), `first` (1–100, default 20).
* `LINEAR_UPDATE_ISSUE`
  * Update fields on an existing issue. At least one update field must be provided.
  * Key inputs: `issue_id` (required), plus any of `title`, `description`, `state_id`, `assignee_id`, `project_id`, `label_ids`, `subscriber_ids`, `priority`, `estimate`.
* `LINEAR_ADD_ISSUE_COMMENT`
  * Add a comment to an issue — useful for triage context or workflow notifications.
  * Key inputs: `issue_id` (required), `comment_body` (required, Markdown).
* `LINEAR_LIST_TEAMS`
  * Fetch teams to look up their internal IDs, names, and keys.
  * Key inputs: `first` (1–100, default 20).
* `LINEAR_GET_PROJECT_PROGRESS`
  * Retrieve a project's progress and status, including scope, completed scope, health, milestones, members, and recent project updates.
  * Key inputs: `project_id` (required).

## Authentication

All Linear tools authenticate with a **personal API key** (OAuth is not supported). Generate one in Linear under **Settings** → **Security & access** → **Personal API keys**, then store it as a `LINEAR_API_KEY` secret in your workspace.

Each step takes a single config field:

| Config field | Description                                         |
| ------------ | --------------------------------------------------- |
| `api_key`    | Your Linear API key (select from workspace secrets) |

**Note**: Treat API keys as sensitive information and never commit them to public repositories.

## Usage Examples

### Example: Look up a team and create an issue

Fetch your teams once to find the internal team ID, then create an issue in that team:

```yaml theme={null}
- id: list_teams
  tool: LINEAR_LIST_TEAMS
  config:
    - name: api_key
      secret: "YOUR_LINEAR_SECRET"
  input:
    - name: first
      value: 50
- id: create_issue
  tool: LINEAR_CREATE_ISSUE
  config:
    - name: api_key
      secret: "YOUR_LINEAR_SECRET"
  input:
    - name: team_id
      value: "TEAM_UUID_FROM_LIST_TEAMS"
    - name: title
      value: "Investigate checkout error spike"
    - name: description
      value: |
        ## Summary
        Error rate on the checkout endpoint doubled since the last deploy.
    - name: priority
      value: 2
```

### Example: Weekly progress digest

Collect issues updated in the past week and the current project status, then summarize with an AI step:

```yaml theme={null}
- id: recent_issues
  tool: LINEAR_GET_ISSUES
  config:
    - name: api_key
      secret: "YOUR_LINEAR_SECRET"
  input:
    - name: project_id
      value: "PROJECT_UUID"
    - name: updated_after
      value: "2026-07-07T00:00:00Z"
    - name: first
      value: 100
- id: project_progress
  tool: LINEAR_GET_PROJECT_PROGRESS
  config:
    - name: api_key
      secret: "YOUR_LINEAR_SECRET"
  input:
    - name: project_id
      value: "PROJECT_UUID"
- id: write_digest
  tool: OPENAI_INVOKE
  input:
    - name: prompt
      value: |
        Write a short weekly status update from this data.

        ==Recently updated issues==
        {{steps.recent_issues.result.issues}}

        ==Project progress==
        {{steps.project_progress.result.project}}
```

## Notes

* **IDs, not names**: All references (`team_id`, `state_id`, `assignee_id`, `project_id`, `label_ids`) are Linear's internal identifiers. Use `LINEAR_LIST_TEAMS` and `LINEAR_GET_ISSUES` to discover them.
* **List inputs**: `label_ids` and `subscriber_ids` accept a JSON array (e.g. `["id1", "id2"]`) or a comma-separated string (`id1, id2`).
* **Updates replace lists**: In `LINEAR_UPDATE_ISSUE`, `label_ids` and `subscriber_ids` replace the existing lists rather than appending to them.
* **Fields cannot be cleared**: Empty values are ignored on update, so you cannot blank out a title or description — only overwrite it. `LINEAR_UPDATE_ISSUE` fails if no update field is provided.
* **Pagination**: `LINEAR_GET_ISSUES` and `LINEAR_LIST_TEAMS` return at most 100 items per run. A `pageInfo` object (`hasNextPage`, `endCursor`) is returned, but there is no cursor input, so only the first page is retrievable in a single step. Narrow results with filters instead.
* **Error handling**: `LINEAR_GET_PROJECT_PROGRESS` returns an `error` object in its output instead of failing the step when the request fails.