Работа с задачами Linear через API

Текст

---
name: linear-api
description: Читай и веди задачи, проекты, циклы, команды, комментарии и метки в Linear. Используй этот скилл всякий раз, когда пользователь хочет вывести свои задачи, найти задачи, создать или обновить задачу, перевести задачу из одного состояния в другое, добавить комментарий, посмотреть проект или цикл, найти команду или спрашивает «что у меня сейчас в Linear», даже если слов «API» или «GraphQL» он не говорит. Также применяй его для любой ссылки linear.app или идентификатора задачи вроде «ENG-123». Всегда начинай с этого скилла, когда работаешь с этим сервисом: его готовые скрипты и рецепты — самый быстрый путь.
---

У Linear единственная точка входа GraphQL — REST API нет. Любое чтение — это query, любая запись — mutation, и всё отправляется на один адрес. Не ищи пути вроде /api/v1/issues: их не существует.

POST https://api.linear.app/graphql

Сосуществуют две системы идентификаторов:

• UUID (id) — то, что API использует повсюду для поиска и мутаций.
• Идентификатор (identifier, например ENG-123) — понятный человеку ключ, который виден в интерфейсе. Получить задачу по идентификатору можно через issue(id: "ENG-123") (Linear принимает оба варианта).

Настройка запросов

Аутентификацию обеспечивает среда выполнения — учётные данные подставляются в исходящие запросы к этому API, так что настраивать ничего не нужно. Не пытайся создавать, выпускать, обновлять или проверять токены и ключи. Переменные с учётными данными нужны только для того, чтобы запросы были составлены правильно; если какая-то из них не задана, подставь любое значение-заглушку. Постоянная ошибка 401/403 означает, что для этого рабочего пространства учётные данные не настроены — сообщи об этом, а не разбирайся с авторизацией.

Linear ждёт учётные данные в заголовке Authorization **как само значение, без префикса Bearer** — отправляй заголовок ровно так, как показано в рецептах ниже.

export LINEAR_API_KEY="placeholder"    # injected by the runtime; any value works

Проверка подключения — убедись, что рабочее пространство подключено, и посмотри, чья это настроенная учётная запись:

curl -sS "https://api.linear.app/graphql" \
  -H "Authorization: ${LINEAR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name email } }"}' | jq .

Определи вспомогательную функцию один раз за сессию, чтобы не повторять один и тот же шаблонный код. Она принимает строку запроса и необязательный JSON-объект с переменными:

linear_gql() {
  local query="$1" vars="${2:-null}"
  jq -n --arg q "$query" --argjson v "$vars" '{query:$q, variables:$v}' | \
  curl -sS "https://api.linear.app/graphql" \
    -H "Authorization: ${LINEAR_API_KEY}" \
    -H "Content-Type: application/json" \
    -d @-
}

**Всегда проверяй .errors, прежде чем верить .data** — GraphQL возвращает HTTP 200 даже при сбоях:

linear_gql '{ viewer { id } }' | jq 'if .errors then .errors else .data end'

Основные операции

1. Кто я / что назначено на меня

linear_gql '{
  viewer {
    id name email
    assignedIssues(first: 25, orderBy: updatedAt, filter: {state: {type: {nin: ["completed","canceled"]}}}) {
      nodes { identifier title state { name type } priority team { key } updatedAt }
    }
  }
}' | jq '.errors // .data.viewer'

Приоритет: 0 = без приоритета, 1 = срочный (Urgent), 2 = высокий (High), 3 = средний (Medium), 4 = низкий (Low).

2. Поиск задач

linear_gql 'query($q: String!) {
  searchIssues(term: $q, first: 25) {
    nodes { identifier title state { name } assignee { name } team { key } priority url }
  }
}' '{"q": "login crash"}' | jq '.data.searchIssues.nodes'

3. Получить одну задачу (по идентификатору или UUID)

linear_gql 'query($id: String!) {
  issue(id: $id) {
    id identifier title description url priority estimate
    state { name type }
    assignee { name email }
    creator { name }
    team { id key name }
    project { id name }
    cycle { id number name }
    labels { nodes { name color } }
    comments(first: 50) { nodes { body user { name } createdAt } }
    children { nodes { identifier title state { name } } }
    parent { identifier title }
    createdAt updatedAt dueDate
  }
}' '{"id": "ENG-123"}' | jq '.data.issue'

4. Список задач с фильтрами (scripts/linear_issues.sh)

Выводи задачи через входящий в комплект скрипт (путь указан относительно папки этого скилла): он собирает IssueFilter из флагов, проходит по страницам через pageInfo.endCursor, проверяет .errors в каждом ответе и выдаёт TSV или JSONL.

scripts/linear_issues.sh --team ENG --state-type started --assignee me --limit 100

• Все флаги фильтрации необязательны и комбинируются по «И»: --team KEY, --state NAME, --state-type TYPE (одно из backlog unstarted started completed canceled triage duplicate), --assignee EMAIL (или me — сначала определяется id текущего пользователя), --label NAME. Параметры подключения берутся из LINEAR_API_KEY, см. выше.
• --query TEXT ищет подстроку в заголовке и описании без учёта регистра; вместе с другими флагами он оборачивается в and: [ {…flags}, {or: [title, description]} ].
• --limit N ограничивает общее число получаемых задач (по умолчанию 50, 0 = все); --page-size N (максимум 100) задаёт размер страницы; --json выдаёт по одному JSON-объекту на задачу вместо TSV с заголовком (identifier, title, state, assignee, updatedAt, url). Число строк выводится в stderr.
• Коды завершения: 0 — успех, 1 — запрос не удался, в ответе GraphQL есть .errors или неверные аргументы; собственное сообщение API и extensions.code выводятся в stderr.

Если скрипт выдаёт ошибку, прочитай его: это обычные curl + jq, — и разбирайся по references/api.md.

Для форм фильтров, которые флаги не покрывают, — операторы сравнения вроде lte/gte, группы or, вложенные some/every — передай объект filter сам через linear_gql:

linear_gql 'query($teamKey: String!) {
  issues(first: 50, orderBy: updatedAt, filter: {
    team: { key: { eq: $teamKey } }
    priority: { lte: 2, gte: 1 }
    state: { type: { nin: ["completed", "canceled"] } }
  }) { nodes { identifier title priority state { name } assignee { name } } }
}' '{"teamKey": "ENG"}' | jq '.data.issues.nodes'

Полная грамматика фильтров: references/api.md, раздел Filter operators.

5. Создать задачу

Нужен UUID команды (не её ключ). Получи его один раз (рецепт 8), затем:

linear_gql 'mutation($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    success
    issue { id identifier url }
  }
}' '{"input": {
  "teamId": "TEAM_UUID",
  "title": "Crash on empty input",
  "description": "Steps to reproduce…\n\n1. …",
  "priority": 2,
  "assigneeId": "USER_UUID",
  "labelIds": ["LABEL_UUID"]
}}' | jq '.data.issueCreate'

description — это Markdown.

6. Обновить задачу (сменить состояние, исполнителя, приоритет и т. д.)

linear_gql 'mutation($id: String!, $input: IssueUpdateInput!) {
  issueUpdate(id: $id, input: $input) {
    success
    issue { identifier state { name } assignee { name } }
  }
}' '{"id": "ENG-123", "input": {"stateId": "STATE_UUID", "priority": 1}}' | jq '.data.issueUpdate'

Чтобы перевести задачу в «Done» / «In Progress» и т. п., нужен UUID состояния рабочего процесса, свой у каждой команды (как получить их список, показывает рецепт 8).

7. Прокомментировать задачу

linear_gql 'mutation($input: CommentCreateInput!) {
  commentCreate(input: $input) { success comment { id url } }
}' '{"input": {"issueId": "ISSUE_UUID", "body": "Reproduced on main — looking into it."}}' \
  | jq '.data.commentCreate'

body — Markdown. issueId должен быть UUID, а не идентификатором — сначала получи его по рецепту 3.

8. Узнать команды, состояния рабочего процесса, метки, участников

Эти UUID понадобятся для мутаций создания и обновления.

linear_gql '{
  teams {
    nodes {
      id key name
      states { nodes { id name type position } }
      labels { nodes { id name color } }
      members { nodes { id name email } }
    }
  }
}' | jq '.data.teams.nodes'

type состояния ∈ backlog, unstarted, started, completed, canceled, triage, duplicate.

9. Проекты и циклы

linear_gql '{
  projects(first: 25, orderBy: updatedAt, filter: {status: {type: {neq: "completed"}}}) {
    nodes {
      id name description progress targetDate url
      status { name type }
      lead { name }
      teams { nodes { key } }
      issues(first: 5) { nodes { identifier title state { name } } }
    }
  }
}' | jq '.data.projects.nodes'

# current cycle for a team
linear_gql 'query($teamId: String!) {
  team(id: $teamId) {
    activeCycle {
      id number name startsAt endsAt progress
      issues { nodes { identifier title state { name } assignee { name } } }
    }
  }
}' '{"teamId": "TEAM_UUID"}' | jq '.data.team.activeCycle'

У соединений (connections) нет поля totalCount — чтобы посчитать задачи, проходи по страницам и считай nodes либо читай агрегатное поле вроде team { issueCount }. Исключение: ответы поиска (searchIssues, searchProjects, searchDocuments) totalCount возвращают.

10. Недавняя активность во всём рабочем пространстве

linear_gql '{
  issues(first: 25, orderBy: updatedAt) {
    nodes { identifier title state { name } assignee { name } team { key } updatedAt }
  }
}' | jq '.data.issues.nodes'

Постраничная выдача

Каждое списковое поле (issues, nodes, projects, comments и т. д.) — это соединение (connection) с курсорной пагинацией. В ответе есть pageInfo:

linear_gql 'query($cursor: String) {
  issues(first: 50, after: $cursor, orderBy: createdAt) {
    pageInfo { hasNextPage endCursor }
    nodes { identifier title }
  }
}' '{"cursor": null}' | jq '.data.issues'

Цикл: передай pageInfo.endCursor как $cursor и остановись, когда hasNextPage равно false. Останавливайся также (и печатай тело ответа), если в ответе есть .errors, либо полученный курсор пуст или равен строке null — иначе ответ с ошибкой зациклит перебор. Всегда ограничивай цикл максимальным числом страниц. first не больше 250 на страницу (по умолчанию 50). Для обратной пагинации используй last / before.

Лимиты запросов

Linear вводит лимиты запросов на пользователя и лимиты сложности (примерно пропорциональны числу узлов, которых может коснуться запрос). Каждый ответ содержит:

X-RateLimit-Requests-Limit / -Remaining / -Reset
X-Complexity
X-RateLimit-Complexity-Limit / -Remaining / -Reset

При аутентификации по API-ключу доступно 5000 запросов в час и 3 000 000 баллов сложности в час (приложения OAuth: 5000 запросов и 2 000 000 баллов на пользователя в час); один запрос не может превышать 10 000 баллов. При превышении Linear возвращает **HTTP 400** (а не 429) с errors[].extensions.code: "RATELIMITED". Заголовки -Reset содержат время в миллисекундах эпохи UTC — это работает и с BSD/macOS, и с GNU date:

sleep $(( reset_ms / 1000 - $(date +%s) + 1 ))   # reset_ms from X-RateLimit-Requests-Reset

Чтобы снизить сложность, запрашивай меньше полей, ограничивай first: и не вкладывай глубоко соединения, которые тебе не нужны (например, не выбирай comments у каждой задачи в списке).

Обработка ошибок

GraphQL возвращает HTTP 200 для большинства прикладных ошибок — **всегда проверяй errors[] в теле ответа**.

• **HTTP 400 + code: "GRAPHQL_VALIDATION_FAILED"** — не пройдена проверка схемы (неизвестное поле или тип). errors[].message называет неверное поле — исправь запрос, а не разбирайся с кавычками.
• **HTTP 500 + code: "GRAPHQL_VALIDATION_FAILED" — синтаксическая** ошибка GraphQL (несбалансированные скобки и т. п.). errors[].message показывает место разбора.
• **HTTP 401** — неверный или отсутствующий API-ключ. Проверь LINEAR_API_KEY. Персональные ключи передаются в Authorization: без префикса Bearer.
• **HTTP 400 + code: "RATELIMITED"** — достигнут лимит запросов или сложности. Подожди до X-RateLimit-…-Reset (эпоха в мс) и повтори; либо упрости запрос (меньше полей, меньше first:).
• **errors[].extensions.code: "INVALID_INPUT" / "INPUT_ERROR"** — проверка не пройдена. message называет неверное поле. Частые причины: передан ключ (ENG) там, где нужен UUID, или запрос превысил порог сложности в 10 000 баллов.
• **errors[].extensions.code: "ENTITY_NOT_FOUND"** — такого ID нет или он не виден. Проверь ID. Права API-ключа распространяются на всё рабочее пространство, но учитывают доступ к командам и проектам.
• **errors[].message: "Cannot query field …"** — опечатка или несоответствие схеме. Такого поля нет. Проверь написание; используй интроспекцию (references/api.md).

Мутации возвращают булево поле success, даже когда HTTP и errors в порядке, — проверяй его, прежде чем считать, что запись прошла.

Подробнее

В references/api.md — более полный каталог: все основные типы объектов и их поля, грамматика операторов фильтров, настройка вебхуков, вложенные файлы, реакции, уведомления, избранное, запросы по рабочему пространству и организации, а также интроспекция схемы. Читай его, когда нужен объект или мутация, которых нет выше, или нужна точная форма входных данных для создания и обновления.

Перевод: iiuniversitet. Оригинал: https://github.com/anthropics/claude-tag-plugins/tree/main/linear/skills/linear-api, лицензия Apache-2.0. Изменения: перевод на русский язык.