Grimoire

Ghid Linear pentru issues și proiecte

4 min read

Ghid Linear pentru issues și proiecte

Ce face

linear este capabilitatea pentru lucrul cu Linear prin API-ul GraphQL: citește și modifică issues, proiecte, echipe, stări de workflow, label-uri, utilizatori și documente.

Nu folosește MCP server, nu cere OAuth flow și nu adaugă dependențe speciale. Mecanismul de bază este un request POST către endpoint-ul Linear, autentificat cu variabila de mediu LINEAR_API_KEY.

Endpoint-ul canonic este:

https://api.linear.app/graphql

Header-ul de autentificare pentru personal API keys este:

Authorization: $LINEAR_API_KEY

Nu se pune prefix Bearer pentru acest tip de cheie. Dacă îl pui, request-ul e greșit.

Când îmi folosește

Folosește linear când vrei operații verificabile și scriptabile fără să intri în interfața web.

Exemple bune:

  • vezi userul curent din API;
  • listezi echipele și cheile lor;
  • găsești un issue după identificator, de tip ABC-123;
  • cauți issues după text;
  • listezi issues asignate ție;
  • vezi workflow states pentru o echipă;
  • muți un issue într-un status anume;
  • creezi un issue cu titlu, descriere și prioritate;
  • adaugi comentarii;
  • setezi prioritate, due date, label-uri sau proiect;
  • listezi proiecte, membri, label-uri și documente.

Operațiile de citire sunt sigure implicit. Operațiile de scriere — creare, update, asignare, comentariu, status, label, due date sau proiect — schimbă sistemul sursă și trebuie cerute explicit, cu țintă clară.

All guides

Cum îl invoc / declanșez

Capabilitatea există ca skill numit linear, cu descrierea: “Linear: manage issues, projects, teams via GraphQL + curl.”

Prerechizite:

  • variabila de mediu LINEAR_API_KEY;
  • comanda curl;
  • pentru formatare JSON, python3 -m json.tool sau jq.

Cheia personală se obține din Linear Settings > Account > Security & access > Personal API keys. Pagina org-level Settings > API este pentru OAuth apps și workspace-member keys, nu pentru personal keys.

Modelul minim de request este:

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name } }"}' | python3 -m json.tool

Skill-ul include și un helper Python stdlib, scripts/linear_api.py, fără dependențe suplimentare. Citește aceeași variabilă LINEAR_API_KEY.

Subcomenzi documentate: whoami, list-teams, list-projects, list-states, list-issues, get-issue, search-issues, create-issue, update-issue, update-status, add-comment, list-documents, get-document, search-documents, raw.

Folosește helper-ul pentru răspunsuri rapide. Folosește curl când ai nevoie de GraphQL custom sau filtre inline.

Exemplu practic

Listezi primele 20 de issues:

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(first: 20) { nodes { identifier title priority state { name type } assignee { name } team { key } url } pageInfo { hasNextPage endCursor } } }"}' | python3 -m json.tool

Iei un issue după identificator scurt:

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issue(id: \"ABC-123\") { id identifier title description priority state { id name type } assignee { id name } team { key } project { name } labels { nodes { name } } url } }"}' | python3 -m json.tool

Pentru schimbare de status, întâi listezi workflowStates pentru echipă și iei UUID-ul stării țintă. Numele vizibil, cum ar fi “In Progress”, nu este suficient.

Output / unde aterizează

Output-ul vine din API-ul Linear, de obicei ca JSON formatat. Pentru query-uri primești noduri GraphQL: issues, teams, projects, users, labels, workflow states sau documents.

Pentru mutations, răspunsul include de obicei success și obiectul modificat. Verifică mereu câmpul errors: GraphQL poate întoarce HTTP 200 și totuși să conțină erori.

Linear rămâne sistemul sursă. Skill-ul doar citește sau scrie prin API, în limita cheii folosite.

Limite / gotchas

Toate request-urile sunt POST cu Content-Type: application/json.

issue(id:) acceptă UUID și identificatori scurți precum ABC-123.

Prioritățile sunt numerice: 0 None, 1 Urgent, 2 High, 3 Medium, 4 Low.

Linear are șase tipuri de stare: triage, backlog, unstarted, started, completed, canceled. Fiecare echipă are propriile stări numite; pentru update ai nevoie de stateId.

Dacă stateId lipsește la creare, Linear folosește primul backlog state disponibil.

Documentele Linear au Markdown în câmpul content. ProseMirror JSON este în contentState; contentData nu este un câmp valid. Pentru URL-uri de document, segmentul hex final este slugId; document(id:) acceptă UUID, iar pentru slugId se folosește filtrarea colecției. Nu există root query searchDocuments; căutarea publică se face prin filtru pe titlu.

Linear folosește paginare Relay cu first, after, pageInfo.hasNextPage și pageInfo.endCursor. Limitează rezultatele cu first: N.

Nu expune LINEAR_API_KEY în comenzi, loguri sau documentație publică. O cheie publicată este încă o cheie activă până când e revocată.

Graph View