GitHub API Automation skill for Claude Code

Done well means: the automation uses the least-privileged credential that works, every list call paginates, bulk writes are throttled and dry-run first, webhooks are verified against the raw body and deduped by delivery ID, and nothing destructive runs without confirmation.

Ground rules

• Tokens come from env or the runner (GITHUB_TOKEN, GH_TOKEN, App private key from a secret store). Never paste tokens into scripts, URLs, or logs.
• Default to a dry-run flag on any script that writes. Print what would change, get the user’s confirmation, then run for real. Deleting repos, branches, releases, or closing issues in bulk always requires explicit confirmation.
• Paginate every list endpoint. Default page size is 30; a script without pagination silently processes the first page only.
• Prefer GraphQL when one screen of data needs many REST calls (nested PRs, reviews, checks); prefer REST for writes and simple lists.

Choose the credential

Situation	Credential	Why
Inside a GitHub Actions workflow on the same repo	GITHUB_TOKEN with explicit permissions:	Auto-expires; scoped to the repo; no secret management
One-off personal script	Fine-grained PAT limited to named repos and permissions, short expiry	Classic PATs grant broad scopes across all repos
Org-wide bot, multi-repo automation, webhooks, service	GitHub App (installation tokens)	Not tied to a person; per-install permissions; higher rate limits; 1-hour tokens
Web app acting as the signed-in user	GitHub App user-to-server token (OAuth flow)	Respects both user and app permissions
Interactive terminal work	gh auth login, then gh / gh api	Token in OS keychain

Events from GITHUB_TOKEN do not trigger new workflow runs (except workflow_dispatch and repository_dispatch). If automation must trigger workflows, use a GitHub App token.

Workflow

- [ ] 1. State the goal as API objects (repos, issues, PRs, checks) and read/write needs
- [ ] 2. Pick credential and minimum permissions (table above)
- [ ] 3. Prototype the query with gh api; inspect real payloads
- [ ] 4. Write the script/app with Octokit: pagination, throttling, dry run
- [ ] 5. For apps: webhook endpoint with signature verification and delivery dedupe
- [ ] 6. Run read-only / dry run; review the planned changes with the user
- [ ] 7. Execute; log every mutation with object URL; verify end state

3. Prototype with gh

gh auth status
gh api rate_limit --jq '.resources | {core: .core.remaining, graphql: .graphql.remaining, search: .search.remaining}'

# REST with pagination; --slurp merges pages into one array (recent gh versions)
gh api --paginate "repos/OWNER/REPO/issues?state=open&per_page=100" --jq '.[] | select(.pull_request | not) | [.number, .title] | @tsv'

# Typed fields: -f sends strings, -F converts numbers/booleans/null and reads @file
gh api -X PATCH repos/OWNER/REPO/issues/123 -f state=closed -f state_reason=not_planned

# GraphQL with variables
gh api graphql -F owner=OWNER -F name=REPO -f query='
  query($owner: String!, $name: String!) {
    repository(owner: $owner, name: $name) {
      pullRequests(states: OPEN, first: 50) { nodes { number title reviewDecision author { login } } }
    }
  }' --jq '.data.repository.pullRequests.nodes[]'

# High-level commands with JSON output
gh pr list --state open --json number,title,author,updatedAt --jq '.[] | select(.updatedAt < "2026-01-01")'
gh issue list --label bug --limit 500 --json number,title
gh run list --workflow ci.yml --status failure --limit 20

4. Octokit script (Node, octokit package, ESM)

The octokit package bundles REST, GraphQL, pagination, retry, and throttling plugins.

import { Octokit } from "octokit";

const DRY_RUN = process.env.DRY_RUN !== "false";
const octokit = new Octokit({
  auth: process.env.GITHUB_TOKEN,
  throttle: {
    onRateLimit: (retryAfter, options, _o, retryCount) => retryCount < 2,          // retry twice
    onSecondaryRateLimit: (retryAfter, options) => { console.warn(`secondary limit ${options.method} ${options.url}`); return true; },
  },
});

const [owner, repo] = process.argv.slice(2);
const stale = await octokit.paginate(octokit.rest.issues.listForRepo, {
  owner, repo, state: "open", labels: "needs-info", per_page: 100,
}, (res) => res.data.filter(i => !i.pull_request && Date.parse(i.updated_at) < Date.now() - 30 * 864e5));

for (const issue of stale) {
  console.log(`${DRY_RUN ? "[dry-run] " : ""}close #${issue.number} ${issue.html_url}`);
  if (DRY_RUN) continue;
  await octokit.rest.issues.createComment({ owner, repo, issue_number: issue.number, body: "Closing: no response in 30 days." });
  await octokit.rest.issues.update({ owner, repo, issue_number: issue.number, state: "closed", state_reason: "not_planned" });
}
console.log(`${stale.length} issues ${DRY_RUN ? "would be" : ""} closed`);

For large result sets use octokit.paginate.iterator(...) to stream pages instead of holding everything in memory. GraphQL cursors: octokit.graphql.paginate(query, vars) with pageInfo { hasNextPage endCursor } and a $cursor: String variable.

Python: PyGithub or plain httpx with Authorization: Bearer, following the Link header for pagination.

5. GitHub App with webhooks

import { App, createNodeMiddleware } from "octokit";
import { createServer } from "node:http";

const app = new App({
  appId: process.env.GITHUB_APP_ID!,
  privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,      // PEM from secret store
  webhooks: { secret: process.env.GITHUB_WEBHOOK_SECRET! },
});

app.webhooks.on("issues.opened", async ({ id, octokit, payload }) => {
  if (await seen(id)) return;                            // id = X-GitHub-Delivery
  await octokit.rest.issues.addLabels({
    owner: payload.repository.owner.login, repo: payload.repository.name,
    issue_number: payload.issue.number, labels: ["triage"],
  });
});
app.webhooks.onError((e) => console.error(e));

createServer(createNodeMiddleware(app)).listen(3000);   // serves POST /api/github/webhooks

createNodeMiddleware verifies X-Hub-Signature-256 before dispatching. For a custom framework, verify yourself with @octokit/webhooks (await webhooks.verifyAndReceive({ id, name, signature, payload: rawBody })) or HMAC-SHA256 of the raw body with the webhook secret, compared in constant time to the header after sha256=.

Webhook rules:

• Respond within 10 seconds; enqueue slow work.
• GitHub does not automatically retry failed deliveries. Monitor failures and redeliver from the App settings “Recent deliveries” page or the deliveries REST API.
• Dedupe on X-GitHub-Delivery. Ignore events from your own app (payload.sender.type === "Bot" and your app’s login) to avoid loops.
• Subscribe only to needed events; permissions must match (e.g. issues: write for labels).

Test signatures locally with the bundled script:

export GITHUB_WEBHOOK_SECRET=...                       # same secret as the App
python3 scripts/github_webhook_sig.py sign payload.json          # prints sha256=... header
python3 scripts/github_webhook_sig.py verify payload.json "sha256=abc..."   # exit 0 if valid

Combine with curl to replay a captured delivery: curl -X POST localhost:3000/api/github/webhooks -H "X-GitHub-Event: issues" -H "X-GitHub-Delivery: test-1" -H "X-Hub-Signature-256: $(python3 scripts/github_webhook_sig.py sign payload.json)" -H "Content-Type: application/json" --data-binary @payload.json.

Rate limits

Limit	Value (2025–2026 docs)
REST, PAT/OAuth user	5,000 requests/hour
REST, GITHUB_TOKEN	1,000 requests/hour per repo (higher on Enterprise Cloud)
REST, App installation	5,000/hour, scaling with repos/users up to 12,500 (15,000 on Enterprise Cloud)
GraphQL	5,000 points/hour per user/installation; cost depends on first: sizes
Search API	30 requests/minute authenticated
Secondary	No more than 100 concurrent requests; about 900 REST points/minute; content-creating requests about 80/minute and 500/hour

Practices:

• Run writes serially (or with small concurrency) with a pause between content-creating calls; the throttling plugin handles 403/429 retry-after but cannot undo a burst.
• Read x-ratelimit-remaining / x-ratelimit-reset; stop early instead of hammering.
• Use conditional requests (If-None-Match with the ETag) for polling; 304 responses do not count against the primary limit. Better: replace polling with webhooks.
• Request smaller GraphQL pages if you hit RESOURCE_LIMITS_EXCEEDED or timeouts.
• Send X-GitHub-Api-Version to pin REST behavior; Octokit sets a default.

Gotchas

• Issues list endpoints return PRs too; filter out items with pull_request.
• 403 can mean permission missing, SSO authorization required for the token (X-GitHub-SSO header), secondary rate limit, or a fine-grained PAT not approved by the org. Read the response body before retrying.
• Fine-grained PATs and App tokens cannot see repos outside their selected set; 404 is the “not found or no access” answer.
• App private key with escaped newlines in env (\n literal): replace before use.
• Search results cap at 1,000 per query; split by date ranges for more.
• Writing the same label/comment twice when a script is rerun: make scripts idempotent by checking current state first.

Verification

1. Dry run output lists exactly the intended objects; spot-check three URLs in the browser.
2. After the real run, re-query with the same filter: the expected count is zero (or the new state matches).
3. gh api rate_limit shows headroom remained; no secondary-limit warnings in logs.
4. Webhook endpoint returns 401/400 for a wrong signature (script sign with a different secret) and processes a valid redelivery once.

Output contract

**Goal:** Close stale needs-info issues older than 30 days in org/repo
**Credential:** fine-grained PAT (issues: write on org/repo, expires in 7 days)
**Dry run:** 42 issues listed (attached), confirmed by user
**Executed:** 42 commented + closed, 0 errors; log in stale-close-2026-10-19.txt
**Rate limit:** core remaining 4,870/5,000 after run
**Rerun safety:** script skips issues already closed