用 Claude Code 安全自动化 GitHub API：实战指南

GitHub API 可以让你用代码读取和更新 Issue、Pull Request、Release、workflow 状态、repository 元数据和 Webhook。和 Claude Code 配合时，它很适合把重复的维护工作变成可审查的自动化：新 Issue 初步分类、找出长期未动的 PR、生成 release note 草稿、每天汇总 repository health。

但 GitHub API 自动化也很容易变危险。常见事故包括把 Personal Access Token 打进日志、为了省事使用权限过大的 classic token、只读取第一页却以为拿到了全部数据、遇到 rate limit 后无限重试、Webhook 不验证签名、让 Claude Code 一次性批量关闭或改写大量 Issue。本文的目标不是教你写一个“能跑”的脚本，而是教你写一个不泄露 token、权限可控、失败时可理解的脚本。

构建时请以官方文档为准：GitHub REST API docs、REST API rate limit docs、Webhook delivery validation 和 GitHub GraphQL API。如果你还要把脚本放进团队流程，可以结合 Git workflow 指南 和 GitHub Actions 高级用法 一起设计。

先理解安全架构

安全的 GitHub API 自动化应该从只读开始。先让脚本列出目标对象，确认数据完整，再加入 dry-run，也就是只打印“将要做什么”而不真正修改。最后才在明确的开关下写入，例如设置 APPLY=true 后才加 label 或发评论。

flowchart LR
  A["给 Claude Code 明确目标和禁区"] --> B["用最小权限读取"]
  B --> C["处理分页和限流"]
  C --> D["显示 dry-run 差异"]
  D --> E["人工确认后写入"]
  E --> F["接入定时任务或 Webhook"]

REST API 适合资源级操作，例如列出 PR、给 Issue 加 label、创建 Release、读取 workflow run。它的 URL、HTTP method 和 status code 都很直观，适合初学者和 Claude Code 分步实现。GraphQL API 更适合报表场景，例如一次查询多个 repository、PR 作者、review 状态、label 和 milestone。初学者可以先用 REST 打好基础，等报表需要跨资源字段时再引入 GraphQL。

判断点	REST API	GraphQL API
适合场景	Issue、PR、Release 等单体操作	跨资源报表和 dashboard
上手难度	低，按 endpoint 调试	较高，需要设计 query
给 Claude Code 的任务	一次实现一个 endpoint	先定义 schema 和字段
主要风险	忘记分页、权限不足	query 过大、字段过多

Token 与权限要先收窄

token 就是密码。不要写进代码，不要写进 README 示例，不要放进测试快照，也不要通过 console.log(process.env) 打出来。本文的示例都从 GITHUB_TOKEN 环境变量读取 token，并且不会打印 token 值。

优先使用 fine-grained personal access token，并限制 repository 和 permission。Issue triage 可能需要 Issues: Read and write，stale PR report 只需要 Pull requests: Read-only，release note 草稿通常从 Contents: Read 和 Metadata: Read 开始就够。classic token 的 repo scope 很方便，但覆盖面太大，应该只在短期验证中使用。

在 GitHub Actions 中也要显式写 permissions。只读日报不需要 write 权限；自动加 label 才需要对应的 issues: write 或 pull-requests: write。让 Claude Code 写 workflow 前，先要求它列出“功能、endpoint、需要权限”的表，过大的 scope 会更容易被发现。

可以这样给 Claude Code 下指令：

请创建一个使用 GitHub REST API 的 Node.js 脚本。
要求:
- token 从 process.env.GITHUB_TOKEN 读取。
- 不要打印 token 或 Authorization header。
- owner/repo 从环境变量读取。
- 先做只读版本，不允许更新 Issue、PR 或 Release。
- 使用 fetch，处理 status code、pagination 和 rate-limit header。
- 写一段 README，说明需要的 GitHub 权限。

可直接运行的只读脚本

下面的脚本使用 Node.js 18 以上内置的 fetch，列出 open issue。它不会修改 repository，也不会输出 token。

export GITHUB_TOKEN="github_pat_xxx"
export GITHUB_OWNER="octocat"
export GITHUB_REPO="Hello-World"
node scripts/list-open-issues.mjs

// scripts/list-open-issues.mjs
const { GITHUB_TOKEN, GITHUB_OWNER, GITHUB_REPO } = process.env;

if (!GITHUB_TOKEN || !GITHUB_OWNER || !GITHUB_REPO) {
  throw new Error("Set GITHUB_TOKEN, GITHUB_OWNER, and GITHUB_REPO.");
}

const apiVersion = "2026-03-10";

async function github(path, options = {}) {
  const response = await fetch(`https://api.github.com${path}`, {
    ...options,
    headers: {
      Accept: "application/vnd.github+json",
      Authorization: `Bearer ${GITHUB_TOKEN}`,
      "X-GitHub-Api-Version": apiVersion,
      "User-Agent": "claudecodelab-safe-github-api-example",
      ...(options.headers ?? {}),
    },
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`GitHub API ${response.status}: ${body.slice(0, 500)}`);
  }

  return response.json();
}

const issues = await github(
  `/repos/${encodeURIComponent(GITHUB_OWNER)}/${encodeURIComponent(GITHUB_REPO)}/issues?state=open&per_page=10`,
);

const rows = issues
  .filter((issue) => !issue.pull_request)
  .map((issue) => ({
    number: issue.number,
    title: issue.title,
    labels: issue.labels.map((label) => label.name).join(", "),
    updated: issue.updated_at,
  }));

console.table(rows);

下一步不要直接让脚本关闭 Issue。更稳妥的做法是先输出候选 label、候选评论或候选负责人，并让人确认。真正写入时使用 APPLY=true 之类的明确开关，而且要限制一次最多修改多少条。

分页和限流必须从第一版就处理

很多 GitHub REST 列表 endpoint 都有 pagination。per_page=100 只代表每页最多 100 条，并不代表全部数据。如果 release note generator 只读取第一页，就会漏掉更早合并的 PR；如果 stale PR reporter 只看第一页，就会给出错误的健康状态。

rate limit 也不能靠无限重试解决。遇到 403 或 429 时，应查看 retry-after 和 x-ratelimit-reset header，等待合理时间，并设置最大重试次数。CI 中宁可清晰失败，也不要用死循环消耗 runner 时间。

下面的 helper 会读取 Link header 中的下一页，并在限流时最多等待两次。

// scripts/github-pages.mjs
const token = process.env.GITHUB_TOKEN;
if (!token) throw new Error("Set GITHUB_TOKEN.");

const apiBase = "https://api.github.com";
const apiVersion = "2026-03-10";

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function defaultHeaders() {
  return {
    Accept: "application/vnd.github+json",
    Authorization: `Bearer ${token}`,
    "X-GitHub-Api-Version": apiVersion,
    "User-Agent": "claudecodelab-pagination-example",
  };
}

function parseNextLink(linkHeader) {
  if (!linkHeader) return null;
  for (const part of linkHeader.split(",")) {
    const match = part.match(/<([^>]+)>;\s*rel="([^"]+)"/);
    if (match && match[2] === "next") return match[1];
  }
  return null;
}

async function githubRequest(url, options = {}, attempt = 0) {
  const response = await fetch(url, {
    ...options,
    headers: {
      ...defaultHeaders(),
      ...(options.headers ?? {}),
    },
  });

  if ((response.status === 403 || response.status === 429) && attempt < 2) {
    const retryAfterSeconds = Number(response.headers.get("retry-after") ?? "0");
    const resetSeconds = Number(response.headers.get("x-ratelimit-reset") ?? "0");
    const resetDelayMs = resetSeconds > 0 ? resetSeconds * 1000 - Date.now() : 0;
    const waitMs = Math.max(retryAfterSeconds * 1000, resetDelayMs, 0);

    if (waitMs > 0 && waitMs <= 10 * 60 * 1000) {
      await sleep(waitMs + 1000);
      return githubRequest(url, options, attempt + 1);
    }
  }

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`GitHub API ${response.status}: ${body.slice(0, 500)}`);
  }

  return {
    data: await response.json(),
    nextUrl: parseNextLink(response.headers.get("link")),
  };
}

export async function paginate(path) {
  const items = [];
  let url = path.startsWith("http") ? path : `${apiBase}${path}`;

  while (url) {
    const page = await githubRequest(url);
    if (!Array.isArray(page.data)) {
      throw new Error("paginate() expected an array response.");
    }
    items.push(...page.data);
    url = page.nextUrl;
  }

  return items;
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const owner = process.env.GITHUB_OWNER;
  const repo = process.env.GITHUB_REPO;
  if (!owner || !repo) throw new Error("Set GITHUB_OWNER and GITHUB_REPO.");

  const pulls = await paginate(
    `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/pulls?state=open&per_page=100`,
  );
  console.table(pulls.map((pr) => ({ number: pr.number, title: pr.title, updated: pr.updated_at })));
}

让 Claude Code 重构现有脚本时，可以要求它把所有 api.github.com 直连调用统一到这个 helper，并用 rg "api.github.com" 检查是否还有遗漏。

Webhook 要验证签名并保证幂等

Webhook 适合事件驱动自动化：PR 打开后生成 label 建议，Issue 创建后进入 triage queue，Release 发布后通知其他系统。问题是 Webhook endpoint 通常暴露在公网。如果不验证 x-hub-signature-256，任何人都可以伪造一个看似来自 GitHub 的 JSON。

还要处理 idempotency，也就是同一个 delivery 被处理两次时结果不应重复。GitHub 可能重发 delivery，因此应该记录 x-github-delivery。下面示例用内存 Set 展示结构，生产环境应换成数据库或 Redis。

npm install express
export GITHUB_WEBHOOK_SECRET="your-webhook-secret"
node webhook-server.mjs

// webhook-server.mjs
import crypto from "node:crypto";
import express from "express";

const secret = process.env.GITHUB_WEBHOOK_SECRET;
if (!secret) throw new Error("Set GITHUB_WEBHOOK_SECRET.");

const app = express();
const seenDeliveries = new Set();

function verifySignature(payloadBuffer, signatureHeader) {
  if (!signatureHeader) return false;

  const expected = `sha256=${crypto
    .createHmac("sha256", secret)
    .update(payloadBuffer)
    .digest("hex")}`;

  const actual = Buffer.from(signatureHeader, "utf8");
  const expectedBuffer = Buffer.from(expected, "utf8");

  return actual.length === expectedBuffer.length && crypto.timingSafeEqual(actual, expectedBuffer);
}

app.post("/github/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.get("x-hub-signature-256");
  if (!verifySignature(req.body, signature)) {
    return res.status(401).send("invalid signature");
  }

  const deliveryId = req.get("x-github-delivery");
  if (!deliveryId) return res.status(400).send("missing delivery id");

  if (seenDeliveries.has(deliveryId)) {
    return res.status(202).send("duplicate ignored");
  }
  seenDeliveries.add(deliveryId);

  const event = req.get("x-github-event");
  const payload = JSON.parse(req.body.toString("utf8"));

  console.log(
    JSON.stringify({
      event,
      deliveryId,
      repository: payload.repository?.full_name,
      action: payload.action,
    }),
  );

  return res.status(202).send("accepted");
});

app.listen(process.env.PORT ?? 3000, () => {
  console.log("Listening for GitHub webhooks.");
});

扩展这个 handler 时，要告诉 Claude Code：签名验证前不要解析 payload，不要在 HTTP 请求里直接执行破坏性操作，同一个 delivery ID 不要重复处理。把副作用放到 queue 中，重试会安全很多。

四个具体用例

Issue triage bot 可以检查新 Issue 是否缺少复现步骤，给出 bug、question、needs-repro 等 label 建议。第一版只写日报，不自动评论。等准确度稳定后，再允许它写入少量 label。

stale PR reporter 可以找出 30 天未更新、review request 长期未处理、CI 失败后无人跟进的 PR。安全版本只报告，不自动 close。关闭或批量加 label 应该放到另一个需要确认的命令中。

release note generator 可以收集两个 tag 之间合并的 PR，并按 label 分组为 Added、Fixed、Changed。需要作者、review 和 milestone 时可以考虑 GraphQL；第一版用 REST 也足够。生成内容应保持为草稿，由 maintainer 最后确认。

daily repository health report 可以汇总 open issue、老 PR、失败 workflow、Dependabot alert、最近 release 和 review backlog。给团队看的报告不应只是堆数据，而要列出“今天最该看的 3 件事”。这类流程也适合继续阅读 Claude Code workflow automation 和 review workflow checklist。

常见失败

第一类是 classic token 泄露。不要打印 process.env，不要 dump 完整 request，不要把 Authorization header 写进 CI 日志。可以用 rg "GITHUB_TOKEN|Authorization|process.env" 做人工复核。

第二类是权限过大。只读 report 不需要写权限；PR report 不需要更新 PR；release note 草稿不需要改 repository settings。权限应该从最小开始，真正需要时再加。

第三类是没有 pagination。脚本看起来成功，但实际只处理第一页，最容易产生错误报告。第四类是 rate-limit loop，遇到限制后立即无限重试。第五类是 Webhook 不验签，直接相信外部 JSON。第六类是破坏性批量编辑，比如一次关闭大量 Issue、重写所有 release、给所有 PR 加 label，却没有 dry-run、数量上限、audit log 和 rollback 思路。

Claude Code 应该负责什么

Claude Code 适合生成 API client、helper、测试、README、GitHub Actions schedule 和 review checklist。它不应该替人决定 production token 权限，也不应该绕过人工确认执行破坏性更新。把边界写进 CLAUDE.md：允许的 endpoint、禁止日志、dry-run 规则、一次最多修改多少条、验证命令是什么。

如果团队要把这套方式落地，ClaudeCodeLab 可以协助整理 CLAUDE.md、权限设计、GitHub Actions、review gate 和 Webhook 运维规则。可以从 Claude Code 培训与咨询 开始；个人练习可以先看 免费 cheatsheet 和 模板资源。

结论

GitHub API 与 Claude Code 的组合很强，但前提是把安全边界写清楚。REST 负责直接操作，GraphQL 负责复杂报表；token 使用最小权限；列表必须分页；限流要等待并有上限；Webhook 必须验签；重复 delivery 要幂等处理。

Masa 的实际验证结果是：本文中的只读脚本、pagination helper 和 Webhook 签名验证 server 都整理成了可复制运行的结构。真实项目中，先用 daily report 暴露问题，再逐步加入 label 写入，比一开始就让 bot 自动关闭 Issue 更容易获得团队信任。