Jira and Linear APIs skill for Claude Code

Done well means: automation creates exactly one ticket per real-world thing (no duplicates on retry), queries page to the end without hitting removed endpoints, rich text renders correctly, rate limits are respected from headers rather than guessed, and inbound webhooks are verified before any side effect.

Ground rules

• Secrets (JIRA_API_TOKEN, LINEAR_API_KEY, OAuth client secrets, webhook secrets) come from env or a secret manager. Never commit them or echo them into logs or ticket bodies.
• Use a dedicated service account (or an OAuth app / Linear app actor) for automation so tickets are attributable and access survives staff changes.
• Address things by stable IDs: Jira accountId, field IDs (customfield_10042), transition IDs looked up at runtime; Linear UUIDs for teams, states, and labels.
• Every automated create must carry an external key (alert fingerprint, Sentry issue ID, Zendesk ticket ID) that you can search on before creating.

Workflow

- [ ] 1. Pick auth (table) and confirm the base URL / site
- [ ] 2. Discover IDs: projects/teams, issue types, workflow states, custom fields
- [ ] 3. Write the dedupe key strategy (search-before-create or client-supplied ID)
- [ ] 4. Implement reads with full pagination and field selection
- [ ] 5. Implement writes (create, update, transition, comment) with retries on 429/5xx
- [ ] 6. Receive webhooks: verify signature on raw body, dedupe, process async
- [ ] 7. Dry-run against a sandbox project/team, then verify

1. Auth

Context	Jira Cloud	Linear
Script or internal job	Basic auth email:api_token against https://<site>.atlassian.net	Personal API key in Authorization: <key>
Multi-tenant app acting for users	OAuth 2.0 (3LO); call https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/...	OAuth 2.0; Authorization: Bearer <token>; actor=app for app-attributed actions
Runs inside Jira	Forge app (no stored credentials)	n/a

Jira OAuth: after the token exchange, call GET https://api.atlassian.com/oauth/token/accessible-resources to get the cloudId for each site the user granted. Request offline_access for refresh tokens, and store the rotating refresh token each time it changes.

2. Discover IDs (Jira)

J="https://$JIRA_SITE.atlassian.net/rest/api/3"; A="$JIRA_EMAIL:$JIRA_API_TOKEN"
curl -s -u "$A" "$J/field" | jq '.[] | select(.custom) | {id, name}'           # custom field IDs
curl -s -u "$A" "$J/issue/createmeta/ENG/issuetypes" | jq '.issueTypes[] | {id, name}'
curl -s -u "$A" "$J/issue/ENG-123/transitions" | jq '.transitions[] | {id, name, to: .to.name}'
curl -s -u "$A" "$J/user/[email protected]" | jq '.[0].accountId'

Linear equivalents come from GraphQL: teams { nodes { id key name } }, workflowStates(filter: { team: { key: { eq: "ENG" } } }) { nodes { id name type } }, issueLabels { nodes { id name } }.

3. Dedupe strategy

Tracker	Default
Jira	Store the external key in a custom field or label (ext-sentry-12345); before creating, search labels = "ext-sentry-12345"; also keep a local mapping table external_key -> issue key
Linear	Generate a deterministic UUID v5 from the external key and pass it as id in issueCreate; a retry with the same ID fails instead of duplicating. Link the source with attachmentCreate (URL-keyed)

Keep the local mapping table as the primary check; search is the fallback for rows created before the table existed. Serialize creates per external key (a lock or unique constraint) so two workers cannot race.

4. Reads

Jira search uses the enhanced JQL endpoint. The old /rest/api/3/search with startAt paging has been retired on Cloud; code still calling it must migrate.

import os, requests

def jira_search(jql: str, fields: list[str]):
    s = requests.Session()
    s.auth = (os.environ["JIRA_EMAIL"], os.environ["JIRA_API_TOKEN"])
    url = f"https://{os.environ['JIRA_SITE']}.atlassian.net/rest/api/3/search/jql"
    token = None
    while True:
        body = {"jql": jql, "fields": fields, "maxResults": 100}
        if token:
            body["nextPageToken"] = token
        r = s.post(url, json=body, timeout=30)
        r.raise_for_status()
        data = r.json()
        yield from data.get("issues", [])
        token = data.get("nextPageToken")
        if not token or data.get("isLast"):
            break

• Request fields explicitly; the enhanced endpoint returns little more than IDs by default.
• Totals are not returned in the page; use POST /rest/api/3/search/approximate-count when a count is needed for UI.
• Always add an ORDER BY (e.g. ORDER BY updated ASC, key ASC) for incremental sync, and query updated >= "<last_sync - 5m>" with an overlap window.

Linear uses Relay cursors; max first is 250 but smaller pages keep complexity down:

import { LinearClient } from "@linear/sdk";
const linear = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

let issues = await linear.issues({
  first: 100,
  filter: { team: { key: { eq: "ENG" } }, state: { type: { nin: ["completed", "canceled"] } } },
});
const all = [...issues.nodes];
while (issues.pageInfo.hasNextPage) { issues = await issues.fetchNext(); all.push(...issues.nodes); }

SDK model properties like issue.assignee are lazy and each costs a request; for bulk reads send one raw GraphQL query selecting exactly the nested fields you need (linear.client.rawRequest(query, vars)).

For a cheat sheet of JQL clauses and Linear filter shapes (dates, status categories, relative times, empty checks, cycles, sub-issues), read references/query-cheatsheet.md when composing a non-trivial query.

5. Writes

Jira v3 rich text fields (description, comment body, textarea custom fields) require Atlassian Document Format (ADF) JSON, not Markdown or wiki markup:

{
  "fields": {
    "project": { "key": "ENG" },
    "issuetype": { "id": "10004" },
    "summary": "Checkout 5xx spike on api-gateway",
    "labels": ["ext-pagerduty-Q1W2E3", "automated"],
    "assignee": { "id": "5b10ac8d82e05b22cc7d4ef5" },
    "description": {
      "type": "doc", "version": 1,
      "content": [
        { "type": "paragraph", "content": [{ "type": "text", "text": "Error rate above 2% for 10 minutes." }] },
        { "type": "paragraph", "content": [{ "type": "text", "text": "Runbook", "marks": [{ "type": "link", "attrs": { "href": "https://runbooks.example.com/checkout" } }] }] }
      ]
    }
  }
}

• POST /rest/api/3/issue creates; POST /rest/api/3/issue/bulk takes up to 50.
• Status changes are transitions, not field edits: look up the transition ID by target status name for that issue, then POST /rest/api/3/issue/{key}/transitions with {"transition":{"id":"31"}}. Transitions can require screen fields (resolution); include them in fields.
• PUT /rest/api/3/issue/{key}?notifyUsers=false for bulk edits to avoid email storms (needs admin-level permission for the flag).
• Linear issueCreate takes Markdown in description, priority 0 (none) to 4 (low) with 1 = urgent, and IDs for teamId, stateId, labelIds, assigneeId.

mutation Create($input: IssueCreateInput!) {
  issueCreate(input: $input) { success issue { id identifier url } }
}

Rate limits:

• Jira returns 429 with Retry-After; honor it plus jitter, cap concurrency at a few requests in flight per site, and back off on 503 the same way.
• Linear: API keys get 2,500 requests/hour and 3,000,000 complexity points/hour per user; OAuth apps 5,000 requests and 2,000,000 points. A single query over 10,000 points is rejected. Read X-RateLimit-Requests-Remaining and X-Complexity and slow down before zero.

6. Webhooks

Verify over the raw bytes before parsing; respond 200 within a few seconds and process from a queue. Dedupe on the delivery ID.

Source	Signature	Replay/dedupe
Linear	Linear-Signature: hex HMAC-SHA256 of raw body with the webhook signing secret	Reject if body webhookTimestamp (ms) is more than 60 s from now; dedupe on Linear-Delivery
Jira (webhook with a secret configured)	X-Hub-Signature: sha256=<hex> HMAC-SHA256 of raw body	Dedupe on issue ID + timestamp + webhookEvent
Jira without a secret option (older registrations)	None: put a long random token in the URL path, check it in constant time, and allowlist Atlassian egress IPs	Same

import crypto from "node:crypto";
function verifyHex(raw: Buffer, header: string | null, secret: string, prefix = "") {
  const expected = prefix + crypto.createHmac("sha256", secret).update(raw).digest("hex");
  const a = Buffer.from(header ?? ""), b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Linear: verifyHex(raw, req.headers["linear-signature"], process.env.LINEAR_WEBHOOK_SECRET)
// Jira:   verifyHex(raw, req.headers["x-hub-signature"], process.env.JIRA_WEBHOOK_SECRET, "sha256=")

Webhooks registered by OAuth or Connect apps through /rest/api/3/webhook expire (about 30 days) and must be refreshed on a schedule. Linear retries failed deliveries a few times over hours and may disable an endpoint that keeps failing; alert on disabled webhooks.

Loop prevention: when your automation updates an issue, the tracker fires a webhook back. Tag your writes (a label, or check the actor is your service account / app) and ignore events your own integration caused.

Gotchas

• Jira usernames and userKey are gone in Cloud; only accountId works for assignee, reporter, and JQL (assignee = 5b10ac8d... or assignee = currentUser()).
• Custom field IDs differ between sites. Never hardcode them across environments; discover by name at startup and cache.
• JQL string values with spaces or reserved words need quotes; user input in JQL needs escaping or you get JQL injection that widens the query.
• Team-managed and company-managed Jira projects have different field and workflow setup; test on the same project type as production.
• Linear identifier (ENG-123) changes when an issue moves teams; store the UUID.
• Linear archived issues are excluded by default; pass includeArchived: true for sync.

Verification

• Run the create path twice with the same external key in a sandbox project/team: one ticket exists afterwards.
• Page through a JQL query returning more than 300 issues and assert the count matches approximate-count within tolerance; repeat for a Linear filter with more than one page.
• Render a created Jira issue in the UI to confirm ADF (links, lists) displays correctly.
• Post a webhook with a modified body: 401. Replay a captured valid delivery: processed once.
• Watch rate-limit headers during a bulk run: remaining never reaches zero and no 429 loops.