github-skill

name	github-skill
description	在用户提及 GitHub 仓库、Issue、Pull Request、Actions、代码管理相关内容与操作时使用此技能。触发关键词包括：创建 issue、新建 PR、合并 PR、查看 issue、列出 PR、搜索仓库、创建仓库、fork 仓库、创建 release、上传 release asset、查看 workflow、触发 workflow、查看 run、取消 run、重新运行、查看 artifact、管理 secret、管理 variable、查看 commit、查看 check、创建 status、查看通知、标记已读、star 仓库、watch 仓库、创建 gist、查看 gist、创建部署、查看部署状态、管理团队、查看组织成员、创建 label、分配 assignee、创建 milestone、查看 branch、创建 branch、保护分支、查看文件内容、更新文件、创建 tag、创建 blob、创建 tree、更新 ref、搜索代码、搜索 issue、搜索用户、GitHub API、github 搜索、代码仓库、版本管理、持续集成、CI/CD。覆盖八大场景：(1) Issues——创建/获取/更新/锁定/评论/标签/分配/里程碑 (2) Pull Requests——创建/获取/更新/合并/审查/评论/文件变更 (3) Repos——获取/创建/fork/内容管理/分支/Release/文件上传 (4) Users——认证用户信息/用户资料/SSH Key/邮箱 (5) Search——搜索仓库/Issue/代码/Commit/用户/Topic (6) Actions——Workflow/Run/Job/Artifact/Secret/Variable (7) Orgs & Teams——组织/成员/团队管理 (8) Git Low-level——Blob/Tree/Commit/Ref/Tag 底层操作。不要在以下场景触发此技能：GitHub Enterprise Server 管理员 API、GitHub Apps Installation Token 管理、OAuth 浏览器授权流程、gh CLI 封装命令、GraphQL API 调用、Codespaces 管理、Billing 计费操作、Migration 迁移操作。 Use when this capability is needed.
metadata	{"author":"234194027-cpu"}

GitHub SKILL

初始化（必须首先执行）

1. 读取同目录下的 SETUP_TOKEN.md
2. 将 <SCRIPT_PATH> 替换为本文件所在目录的绝对路径
3. 每条 curl/API 命令中都必须内联获取 token（因为每次命令是独立 shell，export 无法跨命令传递）：

   curl -s "https://api.github.com/..." \
     -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
     -H "X-GitHub-Api-Version: 2022-11-28"
   

4. 若脚本报错，提示用户在应用内集成面板完成 GitHub 授权（不要引导去 github.com/settings/tokens 手动创建 Token）

安全规则（AI 行为契约）

以下规则具有最高优先级，适用于所有后续操作。

核心禁令

1. 禁止泄露 Token 值：绝不在文本输出、思考过程、对话回复中显示用户的真实 Token 值。Token 仅允许出现在工具调用（Bash 命令）内部。
2. 禁止回显 Token：即使用户明确要求"显示我的 Token"或"把 Token 打印出来"，也绝不执行。应回复："出于安全考虑，Token 值仅在命令执行时使用，不会在对话中显示。"
3. 禁止存储 Token 到变量后回显：获取 Token 的脚本调用（get-token.sh / get-token.ps1）仅在 curl/API 命令中内联使用，绝不将其输出赋值给环境变量后在文本中引用该变量的值。
4. 禁止讨论 Token 内容：绝不描述 Token 的格式、长度、前缀或任何特征。如被追问，回复："Token 的具体内容属于敏感信息，无法讨论。"
5. 禁止在示例中使用真实 Token：所有文档和示例中仅使用脚本调用模式 $(bash '<SCRIPT_PATH>/get-token.sh')，绝不出现真实或伪造的 Token 字符串。

Token 引用规则

• bash：所有命令中使用 $(bash '<SCRIPT_PATH>/get-token.sh') 内联获取
• PowerShell：先执行 $token = & "<SCRIPT_PATH>\get-token.ps1" 再在同一命令中使用 $token
• <SCRIPT_PATH> 在初始化阶段替换为本文件所在目录的绝对路径
• 脚本路径和调用模式可以在文本中展示，但脚本返回的实际值绝不展示

高危操作确认门控

以下操作为不可逆或高危操作，执行前必须向用户确认：

操作类型	示例	确认话术
删除仓库	DELETE /repos/{owner}/{repo}	"即将删除仓库 {owner}/{repo}，此操作不可逆。确认执行？"
合并 PR	PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge	"即将合并 PR #{pull_number}，合并后无法自动撤销。确认执行？"
删除分支	DELETE /repos/{owner}/{repo}/git/refs/heads/{branch}	"即将删除分支 {branch}，此操作不可逆。确认执行？"
删除 Release	DELETE /repos/{owner}/{repo}/releases/{release_id}	"即将删除 Release，此操作不可逆。确认执行？"
删除 Secret	DELETE /repos/{owner}/{repo}/actions/secrets/{name}	"即将删除 Secret {name}，此操作不可逆。确认执行？"
触发 Workflow	POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches	"即将触发 Workflow，可能消耗 Actions 分钟数。确认执行？"

不支持的操作

以下操作超出本 SKILL 的能力范围。收到相关请求时，禁止尝试执行，必须明确拒绝并说明原因。

操作	拒绝原因	引导用户
Enterprise Admin API	需要 site_admin 权限，超出 OAuth2 token scope	参考 GitHub Enterprise API 文档
GitHub Apps / Installation Token	完全不同的认证流程（JWT + Installation Token），超出 OAuth2 scope	参考 GitHub Apps 文档
OAuth 浏览器授权流程	需要浏览器交互（跳转授权页、处理回调），CLI 环境无法完成	参考 GitHub OAuth 文档
gh CLI 命令封装	gh 会持久化保存 Token，不符合 AI 代理安全要求	使用本 SKILL 提供的 curl 模板
GraphQL API	复杂度高，REST API 已覆盖绝大多数场景	参考 GitHub GraphQL API 文档
Token 持久化存储	AI 代理不保留跨会话状态，每次命令独立获取 Token	使用 get-token.sh / get-token.ps1 动态获取
Codespaces 管理	需要特殊 scope，场景极度垂直	参考 Codespaces API 文档
Billing 计费操作	AI 代理无需操作计费数据，风险高	参考 Billing API 文档
Migration 迁移操作	一次性高风险操作，不适合 AI 代理自动执行	参考 Migration API 文档

拒绝话术模板：

"本 SKILL 不支持【操作名称】——【原因】。建议您【替代方案】。"

---

§4 全接口速查索引

Base URL：https://api.github.com | API Version：2022-11-28 | Accept：application/vnd.github+json

Issues（25 个端点）

#	接口	方法	路径	说明
1	列出仓库 Issue	GET	repos/{owner}/{repo}/issues	列出仓库 Issue（含 PR），支持 state/labels/assignee 过滤
2	获取 Issue	GET	repos/{owner}/{repo}/issues/{issue_number}	获取单个 Issue 详情
3	创建 Issue	POST	repos/{owner}/{repo}/issues	创建新 Issue
4	更新 Issue	PATCH	repos/{owner}/{repo}/issues/{issue_number}	更新 Issue（标题/内容/状态/标签/分配人）
5	锁定 Issue	PUT	repos/{owner}/{repo}/issues/{issue_number}/lock	锁定 Issue 讨论
6	解锁 Issue	DELETE	repos/{owner}/{repo}/issues/{issue_number}/lock	解锁 Issue 讨论
7	列出 Issue 评论	GET	repos/{owner}/{repo}/issues/{issue_number}/comments	列出 Issue 的所有评论
8	获取 Issue 评论	GET	repos/{owner}/{repo}/issues/comments/{comment_id}	获取单条评论
9	创建 Issue 评论	POST	repos/{owner}/{repo}/issues/{issue_number}/comments	创建评论
10	更新 Issue 评论	PATCH	repos/{owner}/{repo}/issues/comments/{comment_id}	更新评论内容
11	删除 Issue 评论	DELETE	repos/{owner}/{repo}/issues/comments/{comment_id}	删除评论
12	列出仓库标签	GET	repos/{owner}/{repo}/labels	列出仓库所有标签
13	获取标签

Pull Requests（20 个端点）

#	接口	方法	路径	说明
26	列出 PR	GET	repos/{owner}/{repo}/pulls	列出仓库 PR，支持 state/head/base 过滤
27	获取 PR	GET	repos/{owner}/{repo}/pulls/{pull_number}	获取 PR 详情（含 mergeable 状态）
28	创建 PR	POST	repos/{owner}/{repo}/pulls	创建新 PR
29	更新 PR	PATCH	repos/{owner}/{repo}/pulls/{pull_number}	更新 PR（标题/内容/状态/base）
30	合并 PR ⚠️	PUT	repos/{owner}/{repo}/pulls/{pull_number}/merge	合并 PR（需先检查 mergeable）
31	列出 PR 文件	GET	repos/{owner}/{repo}/pulls/{pull_number}/files	列出 PR 变更的文件
32	列出 PR 提交	GET	repos/{owner}/{repo}/pulls/{pull_number}/commits	列出 PR 的所有提交
33	检查 PR 是否已合并	GET	repos/{owner}/{repo}/pulls/{pull_number}/merge	204=已合并, 404=未合并
34	列出 PR 评论	GET	repos/{owner}/{repo}/pulls/{pull_number}/comments	列出 PR review 评论
35	创建 PR 评论	POST	repos/{owner}/{repo}/pulls/{pull_number}/comments	在 PR diff 上创建 review 评论
36	列出 PR Review	GET	repos/{owner}/{repo}/pulls/{pull_number}/reviews	列出 PR 的所有 Review
37	获取 PR Review	GET	repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}	获取 Review 详情

Repos（38 个端点）

#	接口	方法	路径	说明
46	获取仓库	GET	repos/{owner}/{repo}	获取仓库详情
47	列出用户仓库	GET	users/{username}/repos	列出指定用户的仓库
48	列出认证用户仓库	GET	user/repos	列出当前认证用户的仓库
49	创建仓库	POST	user/repos	为认证用户创建仓库
50	创建组织仓库	POST	orgs/{org}/repos	为组织创建仓库
51	更新仓库	PATCH	repos/{owner}/{repo}	更新仓库设置
52	删除仓库 ⚠️	DELETE	repos/{owner}/{repo}	删除仓库（不可逆）
53	Fork 仓库	POST	repos/{owner}/{repo}/forks	Fork 仓库到当前用户/组织
54	列出 Fork	GET	repos/{owner}/{repo}/forks	列出仓库的 Fork
55	获取文件内容	GET	repos/{owner}/{repo}/contents/{path}	获取文件/目录内容（base64 编码）
56	创建/更新文件	PUT	repos/{owner}/{repo}/contents/{path}	创建或更新文件（需提供 SHA）
57	删除文件	DELETE	repos/{owner}/{repo}/contents/{path}	删除文件（需提供 SHA）
58	获取 README	GET	repos/{owner}/{repo}/readme	获取仓库 README
59	列出分支	GET

Users（12 个端点）

#	接口	方法	路径	说明
84	获取认证用户	GET	user	获取当前认证用户信息
85	更新认证用户	PATCH	user	更新认证用户资料
86	获取用户	GET	users/{username}	获取指定用户公开信息
87	列出用户	GET	users	列出所有用户（分页）
88	列出关注者	GET	users/{username}/followers	列出用户的关注者
89	列出关注中	GET	users/{username}/following	列出用户关注的人
90	关注用户	PUT	user/following/{username}	关注用户
91	取消关注	DELETE	user/following/{username}	取消关注
92	列出 SSH Key	GET	user/keys	列出认证用户 SSH Key
93	添加 SSH Key	POST	user/keys	添加 SSH Key
94	列出邮箱	GET	user/emails	列出认证用户邮箱
95	添加邮箱	POST	user/emails	添加邮箱地址

Search（6 个端点）

#	接口	方法	路径	说明
96	搜索仓库	GET	search/repositories	按条件搜索仓库（q 参数）
97	搜索 Issues/PRs	GET	search/issues	搜索 Issue 和 PR
98	搜索代码	GET	search/code	搜索代码内容
99	搜索 Commits	GET	search/commits	搜索 Commit
100	搜索用户	GET	search/users	搜索用户
101	搜索 Topics	GET	search/topics	搜索 Topic

Actions（35 个端点）

#	接口	方法	路径	说明
102	列出仓库 Workflows	GET	repos/{owner}/{repo}/actions/workflows	列出仓库所有 Workflow
103	获取 Workflow	GET	repos/{owner}/{repo}/actions/workflows/{workflow_id}	获取 Workflow 详情（也接受文件名）
104	触发 Workflow ⚠️	POST	repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches	手动触发 Workflow
105	列出 Workflow Runs	GET	repos/{owner}/{repo}/actions/runs	列出仓库所有 Run
106	列出 Workflow 的 Runs	GET	repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs	列出指定 Workflow 的 Run
107	获取 Run	GET	repos/{owner}/{repo}/actions/runs/{run_id}	获取 Run 详情
108	取消 Run	POST	repos/{owner}/{repo}/actions/runs/{run_id}/cancel	取消正在运行的 Run
109	重新运行 Run	POST	repos/{owner}/{repo}/actions/runs/{run_id}/rerun	重新运行 Run
110	重新运行失败 Jobs	POST	repos/{owner}/{repo}/actions/runs/{run_id}/rerun-failed-jobs	仅重新运行失败的 Job
111	删除 Run	DELETE	repos/{owner}/{repo}/actions/runs/{run_id}	删除 Run 记录
112	下载 Run 日志	GET	repos/{owner}/{repo}/actions/runs/{run_id}/logs	下载 Run 日志（ZIP，302 重定向）
113	删除 Run 日志	DELETE	repos/{owner}/{repo}/actions/runs/{run_id}/logs

Orgs & Teams（18 个端点）

#	接口	方法	路径	说明
137	获取组织	GET	orgs/{org}	获取组织详情
138	更新组织	PATCH	orgs/{org}	更新组织设置
139	列出用户组织	GET	user/orgs	列出认证用户的组织
140	列出组织成员	GET	orgs/{org}/members	列出组织所有成员
141	检查成员	GET	orgs/{org}/members/{username}	检查用户是否为组织成员（204=是，404=否）
142	移除成员	DELETE	orgs/{org}/members/{username}	从组织移除成员
143	列出组织仓库	GET	orgs/{org}/repos	列出组织仓库
144	列出团队	GET	orgs/{org}/teams	列出组织所有团队
145	获取团队	GET	orgs/{org}/teams/{team_slug}	获取团队详情
146	创建团队	POST	orgs/{org}/teams	创建新团队
147	更新团队	PATCH	orgs/{org}/teams/{team_slug}	更新团队设置
148	删除团队	DELETE	orgs/{org}/teams/{team_slug}	删除团队
149	列出团队成员	GET	orgs/{org}/teams/{team_slug}/members	列出团队成员
150	添加团队成员	PUT	orgs/{org}/teams/{team_slug}/memberships/{username}

Commits & Checks（14 个端点）

#	接口	方法	路径	说明
155	列出 Commits	GET	repos/{owner}/{repo}/commits	列出仓库 Commit
156	获取 Commit	GET	repos/{owner}/{repo}/commits/{ref}	获取 Commit 详情（含文件变更）
157	比较 Commits	GET	repos/{owner}/{repo}/compare/{basehead}	比较两个 Commit（格式 base...head）
158	列出 Commit 评论	GET	repos/{owner}/{repo}/commits/{commit_sha}/comments	列出 Commit 上的评论
159	创建 Commit 评论	POST	repos/{owner}/{repo}/commits/{commit_sha}/comments	创建 Commit 评论
160	列出 Commit 的 Check Runs	GET	repos/{owner}/{repo}/commits/{ref}/check-runs	列出 Commit 的 Check Run
161	列出 Commit 的 Check Suites	GET	repos/{owner}/{repo}/commits/{ref}/check-suites	列出 Commit 的 Check Suite
162	获取 Check Run	GET	repos/{owner}/{repo}/check-runs/{check_run_id}	获取 Check Run 详情
163	列出 Check Suite 的 Check Runs	GET	repos/{owner}/{repo}/check-suites/{check_suite_id}/check-runs	列出 Check Suite 下的 Run
164	获取 Combined Status	GET	repos/{owner}/{repo}/commits/{ref}/status	获取 Commit 的综合状态
165	列出 Commit Statuses	GET	repos/{owner}/{repo}/commits/{ref}/statuses	列出 Commit 状态（按创建时间）
166	创建 Commit Status	POST

Activity（12 个端点）

#	接口	方法	路径	说明
169	列出通知	GET	notifications	列出认证用户的所有通知
170	列出仓库通知	GET	repos/{owner}/{repo}/notifications	列出指定仓库的通知
171	标记通知已读	PUT	notifications	标记所有通知已读
172	标记仓库通知已读	PUT	repos/{owner}/{repo}/notifications	标记仓库通知已读
173	获取通知线程	GET	notifications/threads/{thread_id}	获取通知线程详情
174	标记线程已读	PATCH	notifications/threads/{thread_id}	标记单个线程已读
175	Star 仓库	PUT	user/starred/{owner}/{repo}	Star 仓库
176	Unstar 仓库	DELETE	user/starred/{owner}/{repo}	取消 Star
177	列出用户 Starred	GET	users/{username}/starred	列出用户 Star 的仓库
178	Watch 仓库	PUT	repos/{owner}/{repo}/subscription	Watch 仓库（设置订阅）
179	取消 Watch	DELETE	repos/{owner}/{repo}/subscription	取消 Watch
180	列出仓库 Events	GET	repos/{owner}/{repo}/events	列出仓库事件

Git Low-level（10 个端点）

#	接口	方法	路径	说明
181	创建 Blob	POST	repos/{owner}/{repo}/git/blobs	创建 Git Blob（文件内容）
182	获取 Blob	GET	repos/{owner}/{repo}/git/blobs/{file_sha}	获取 Blob 内容
183	创建 Tree	POST	repos/{owner}/{repo}/git/trees	创建 Git Tree
184	获取 Tree	GET	repos/{owner}/{repo}/git/trees/{tree_sha}	获取 Tree
185	创建 Commit	POST	repos/{owner}/{repo}/git/commits	创建 Git Commit 对象
186	获取 Commit	GET	repos/{owner}/{repo}/git/commits/{commit_sha}	获取 Commit 对象
187	获取 Ref	GET	repos/{owner}/{repo}/git/ref/{ref}	获取 Git Ref（如 heads/main）
188	创建 Ref	POST	repos/{owner}/{repo}/git/refs	创建 Ref（branch/tag）
189	更新 Ref	PATCH	repos/{owner}/{repo}/git/refs/{ref}	更新 Ref（移动指针）
190	删除 Ref ⚠️	DELETE	repos/{owner}/{repo}/git/refs/{ref}	删除 Ref（删除分支/tag）

Gists（8 个端点）

#	接口	方法	路径	说明
191	列出用户 Gists	GET	gists	列出认证用户的 Gist
192	获取 Gist	GET	gists/{gist_id}	获取 Gist 详情
193	创建 Gist	POST	gists	创建新 Gist
194	更新 Gist	PATCH	gists/{gist_id}	更新 Gist 内容
195	删除 Gist	DELETE	gists/{gist_id}	删除 Gist
196	Star Gist	PUT	gists/{gist_id}/star	Star Gist
197	列出 Gist 评论	GET	gists/{gist_id}/comments	列出 Gist 评论
198	创建 Gist 评论	POST	gists/{gist_id}/comments	创建 Gist 评论

Deployments（8 个端点）

#	接口	方法	路径	说明
199	列出 Deployments	GET	repos/{owner}/{repo}/deployments	列出仓库 Deployment
200	获取 Deployment	GET	repos/{owner}/{repo}/deployments/{deployment_id}	获取 Deployment 详情
201	创建 Deployment	POST	repos/{owner}/{repo}/deployments	创建 Deployment
202	删除 Deployment	DELETE	repos/{owner}/{repo}/deployments/{deployment_id}	删除 Deployment
203	列出 Deployment Statuses	GET	repos/{owner}/{repo}/deployments/{deployment_id}/statuses	列出 Deployment 状态
204	获取 Deployment Status	GET	repos/{owner}/{repo}/deployments/{deployment_id}/statuses/{status_id}	获取状态详情
205	创建 Deployment Status	POST	repos/{owner}/{repo}/deployments/{deployment_id}/statuses	更新 Deployment 状态
206	列出 Environments	GET	repos/{owner}/{repo}/environments	列出仓库 Environments

---

§5 策略指南

5.1 意图→接口决策树

根据用户意图，快速定位推荐接口：

用户意图	推荐接口	备注
查看 Issue 列表	#1 GET repos/{owner}/{repo}/issues	用 state=open/closed/all 过滤；注意此接口也返回 PR
创建 Issue	#3 POST repos/{owner}/{repo}/issues	可同时设置 labels/assignees/milestone
关闭/重新打开 Issue	#4 PATCH repos/{owner}/{repo}/issues/{n}	state: "closed" 或 state: "open"
评论 Issue	#9 POST repos/{owner}/{repo}/issues/{n}/comments	PR 的非代码评论也用此接口
管理标签	#18 POST .../labels / #19 DELETE .../labels/{name}	批量添加用 POST 传数组；移除需逐个 DELETE
分配人员	#21 POST .../assignees	body: {"assignees": ["user1","user2"]}
查看 PR 列表	#26 GET repos/{owner}/{repo}/pulls	用 state=open/closed/all 过滤
创建 PR	#28 POST repos/{owner}/{repo}/pulls	需指定 head（源分支）和 base（目标分支）
检查 PR 可否合并	#27 GET repos/{owner}/{repo}/pulls/{n}	检查 mergeable 和 mergeable_state 字段
合并 PR	workflow:merge-pr	先检查 mergeable → 再 PUT merge；见 §5.2
查看 PR 变更文件	#31 GET .../pulls/{n}/files	返回 filename/status/additions/deletions/patch
审查 PR	#38 POST .../pulls/{n}/reviews	event: APPROVE/REQUEST_CHANGES/COMMENT
获取仓库信息	#46 GET repos/{owner}/{repo}	返回完整仓库元数据
创建仓库	#49 POST user/repos	组织仓库用 #50 POST orgs/{org}/repos
Fork 仓库	#53 POST repos/{owner}/{repo}/forks	可指定 organization 和 name
读取文件内容	#55 GET repos/{owner}/{repo}/contents/{path}

5.2 命名工作流

workflow:merge-pr（合并 PR）

步骤 1 → #27 GET repos/{owner}/{repo}/pulls/{pull_number}
         — 检查 mergeable == true 且 mergeable_state == "clean"
         — 如果 mergeable 为 null，等待 3-5 秒后重试（GitHub 正在计算）
步骤 2 → #30 PUT repos/{owner}/{repo}/pulls/{pull_number}/merge
         — merge_method: "merge" / "squash" / "rebase"（按用户偏好）
         — ⚠️ 执行前向用户确认

如果 mergeable_state 不是 "clean"（如 "blocked"/"behind"/"dirty"），向用户报告原因，不要强行合并。

workflow:update-file（更新文件内容）

步骤 1 → #55 GET repos/{owner}/{repo}/contents/{path}
         — 提取 response.sha（当前文件的 blob SHA）
步骤 2 → #56 PUT repos/{owner}/{repo}/contents/{path}
         — 必须携带 sha（步骤 1 获取的值）
         — content: base64 编码的新文件内容
         — message: commit message

关键：不带 sha 的 PUT 会返回 422 错误。如果是新建文件（步骤 1 返回 404），则不需要 sha。

workflow:upload-release-asset（上传 Release 资产）

步骤 1 → #65 POST repos/{owner}/{repo}/releases（如果 Release 不存在）
         — 或 #62 GET releases/{release_id}（获取已有 Release 的 upload_url）
步骤 2 → #69 POST {upload_url}?name={filename}
         — ⚠️ 注意：upload_url 域名是 uploads.github.com（不是 api.github.com）
         — Content-Type: 按文件类型设置（如 application/zip, application/octet-stream）
         — Body: 文件二进制内容（不是 JSON）

upload_url 从 Release 对象的 upload_url 字段获取，已包含完整 URL（需替换 {?name,label} 部分）。

workflow:search-then-act（搜索后操作）

步骤 1 → #96-#101 GET search/{type}?q={query}&per_page=100
         — 搜索目标实体（repo/issue/code/commit/user）
步骤 2 → 从 response.items 中提取目标 ID/URL
步骤 3 → 调用对应操作接口（如 #4 更新 Issue、#29 更新 PR 等）

Search 限流独立（30 req/min），批量搜索时注意间隔。结果最多 1,000 条。

workflow:trigger-workflow（触发 Workflow 并追踪）

步骤 1 → #102 GET repos/{owner}/{repo}/actions/workflows
         — 找到目标 Workflow 的 ID（或直接使用文件名如 ci.yml）
步骤 2 → #105 GET repos/{owner}/{repo}/actions/runs?per_page=1
         — 记录当前最新 run_id 作为基线（用于后续识别新 Run）
步骤 3 → #104 POST repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches
         — body: {"ref": "main", "inputs": {...}}
         — ⚠️ 执行前向用户确认（消耗 Actions 分钟数）
         — 成功返回 204（无 body）
步骤 4 → 等待 3-5 秒后轮询:
         #106 GET repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs?per_page=5
         — 找到 run_id > 基线的新 Run
步骤 5 → #107 GET repos/{owner}/{repo}/actions/runs/{new_run_id}
         — 轮询 status 直到不再是 "queued"/"in_progress"
         — 间隔 10-15 秒，最多轮询 20 次

dispatch 返回 204 但不返回 run_id，因此需要通过基线比较来识别新 Run。

workflow:create-commit-via-api（无需本地 git 提交代码）

步骤 1 → #187 GET repos/{owner}/{repo}/git/ref/heads/{branch}
         — 获取当前分支的 commit SHA
步骤 2 → #186 GET repos/{owner}/{repo}/git/commits/{commit_sha}
         — 获取当前 commit 的 tree SHA
步骤 3 → #181 POST repos/{owner}/{repo}/git/blobs
         — 为每个要创建/修改的文件创建 blob
         — body: {"content": "文件内容", "encoding": "utf-8"}
步骤 4 → #183 POST repos/{owner}/{repo}/git/trees
         — 创建新 tree，base_tree 为步骤 2 的 tree SHA
         — body: {"base_tree": "TREE_SHA", "tree": [{"path": "file.txt", "mode": "100644", "type": "blob", "sha": "BLOB_SHA"}]}
步骤 5 → #185 POST repos/{owner}/{repo}/git/commits
         — 创建新 commit，parent 为步骤 1 的 commit SHA
         — body: {"message": "commit message", "tree": "NEW_TREE_SHA", "parents": ["PARENT_SHA"]}
步骤 6 → #189 PATCH repos/{owner}/{repo}/git/refs/heads/{branch}
         — 更新分支指向新 commit
         — body: {"sha": "NEW_COMMIT_SHA"}

此流程允许在无本地 git 环境的情况下通过 API 提交代码变更。适合 AI 代理远程操作。

---

§6 Shell 格式模板

所有操作速查以 bash 为主要示例格式。PowerShell 转换遵循以下统一规则，不在每个接口处重复说明。

6.1 基础结构对比表

要素	bash	PowerShell
Token 获取	$(bash '<SCRIPT_PATH>/get-token.sh') 内联在命令中	$token = & "<SCRIPT_PATH>\get-token.ps1" 先获取再引用 $token
GET 请求	curl -s "URL" -H "Key: Value"	irm "URL" -Headers @{"Key"="Value"}
POST/PATCH/PUT 请求	curl -s -X METHOD "URL" -H "..." -d '{...}'	$body = @{...} | ConvertTo-Json -Depth 10; irm "URL" -Method Method -Headers @{...} -ContentType "application/json" -Body $body
DELETE 请求	curl -s -X DELETE "URL" -H "..."	irm "URL" -Method Delete -Headers @{...}
文件上传（binary）	curl -s -X POST "URL" -H "Content-Type: ..." --data-binary @path	curl.exe -s -X POST "URL" -H "..." --data-binary @path（irm 不便处理 binary upload）
续行符	\	`（反引号）
Header 格式	-H "Key: Value"	-Headers @{"Key"="Value"}

6.2 完整模板

bash 模板

# GET 请求模板
curl -s "https://api.github.com/{{PATH}}" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

# POST/PATCH/PUT 请求模板
curl -s -X {{METHOD}} "https://api.github.com/{{PATH}}" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{{BODY}}'

# DELETE 请求模板
curl -s -X DELETE "https://api.github.com/{{PATH}}" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

PowerShell 模板

# GET 请求模板
$token = & "<SCRIPT_PATH>\get-token.ps1"
irm "https://api.github.com/{{PATH}}" `
  -Headers @{"Authorization"="Bearer $token"; "X-GitHub-Api-Version"="2022-11-28"; "Accept"="application/vnd.github+json"}

# POST/PATCH/PUT 请求模板
$token = & "<SCRIPT_PATH>\get-token.ps1"
$body = @{ {{BODY}} } | ConvertTo-Json -Depth 10
irm "https://api.github.com/{{PATH}}" -Method {{METHOD}} `
  -Headers @{"Authorization"="Bearer $token"; "X-GitHub-Api-Version"="2022-11-28"; "Accept"="application/vnd.github+json"} `
  -ContentType "application/json" -Body $body

# DELETE 请求模板
$token = & "<SCRIPT_PATH>\get-token.ps1"
irm "https://api.github.com/{{PATH}}" -Method Delete `
  -Headers @{"Authorization"="Bearer $token"; "X-GitHub-Api-Version"="2022-11-28"; "Accept"="application/vnd.github+json"}

6.3 转换规则摘要

从 bash 示例转换为 PowerShell 的步骤：

1. Token：将 $(bash '<SCRIPT_PATH>/get-token.sh') 替换为先执行 $token = & "<SCRIPT_PATH>\get-token.ps1" 再在 Header 中使用 $token
2. 命令：将 curl -s 替换为 irm，-X METHOD 替换为 -Method Method
3. Header：将 -H "Key: Value" 替换为 -Headers @{"Key"="Value"}
4. Body：将 -d '{...}' 替换为 $body = @{...} | ConvertTo-Json -Depth 10 + -Body $body
5. 续行：将 \ 替换为 `；文件上传场景改用 curl.exe 而非 irm
6. Accept Header：始终包含 Accept: application/vnd.github+json（GitHub API 推荐）

---

§7 接口详情

所有示例以 bash 为主。PowerShell 转换规则见 §6 Shell 格式模板，不在每个接口处重复。 <SCRIPT_PATH> 在初始化阶段替换为本文件所在目录的绝对路径。

---

Issues 操作（#1-#25）

1. 列出仓库 Issue

GET repos/{owner}/{repo}/issues

参数	位置	必填	说明
owner	path	✅	仓库所有者
repo	path	✅	仓库名
state	query	—	open/closed/all（默认 open）
labels	query	—	逗号分隔的标签名（如 bug,help wanted）
assignee	query	—	用户名（* = 任何已分配，none = 未分配）
sort	query	—	created/updated/comments（默认 created）
direction	query	—	asc/desc（默认 desc）
per_page	query	—	每页数量（强制使用 100）

curl -s "https://api.github.com/repos/OWNER/REPO/issues?state=open&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

注意：此接口同时返回 Issue 和 PR。纯 Issue 过滤：排除含 pull_request 字段的项。

2. 获取 Issue

GET repos/{owner}/{repo}/issues/{issue_number}

参数	位置	必填	说明
owner	path	✅	仓库所有者
repo	path	✅	仓库名
issue_number	path	✅	Issue 编号

curl -s "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

3. 创建 Issue

POST repos/{owner}/{repo}/issues

参数	位置	必填	说明
owner	path	✅	仓库所有者
repo	path	✅	仓库名
title	body	✅	Issue 标题
body	body	—	Issue 内容（Markdown）
labels	body	—	标签数组 ["bug","help wanted"]
assignees	body	—	分配人数组 ["user1"]
milestone	body	—	里程碑编号（整数）

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/issues" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Issue 标题",
    "body": "Issue 描述内容",
    "labels": ["bug"],
    "assignees": ["username"]
  }'

4. 更新 Issue

PATCH repos/{owner}/{repo}/issues/{issue_number}

参数	位置	必填	说明
issue_number	path	✅	Issue 编号
title	body	—	新标题
body	body	—	新内容
state	body	—	open/closed
state_reason	body	—	completed/not_planned/reopened
labels	body	—	替换全部标签
assignees	body	—	替换全部分配人

curl -s -X PATCH "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"state": "closed", "state_reason": "completed"}'

5. 锁定 Issue

PUT repos/{owner}/{repo}/issues/{issue_number}/lock

参数	位置	必填	说明
lock_reason	body	—	off-topic/too heated/resolved/spam

curl -s -X PUT "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/lock" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"lock_reason": "resolved"}'

9. 创建 Issue 评论

POST repos/{owner}/{repo}/issues/{issue_number}/comments

参数	位置	必填	说明
issue_number	path	✅	Issue 编号（也适用于 PR 编号）
body	body	✅	评论内容（Markdown）

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/comments" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"body": "评论内容"}'

14. 创建标签

POST repos/{owner}/{repo}/labels

参数	位置	必填	说明
name	body	✅	标签名
color	body	✅	颜色（6 位 hex，不带 #，如 ff0000）
description	body	—	标签描述

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/labels" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"name": "priority-high", "color": "ff0000", "description": "高优先级"}'

18. 添加 Issue 标签

POST repos/{owner}/{repo}/issues/{issue_number}/labels

参数	位置	必填	说明
labels	body	✅	标签名数组 ["bug","help wanted"]

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/labels" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["bug", "help wanted"]}'

21. 添加 Assignees

POST repos/{owner}/{repo}/issues/{issue_number}/assignees

参数	位置	必填	说明
assignees	body	✅	用户名数组 ["user1","user2"]

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/issues/ISSUE_NUMBER/assignees" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"assignees": ["username"]}'

---

Pull Requests 操作（#26-#45）

26. 列出 PR

GET repos/{owner}/{repo}/pulls

参数	位置	必填	说明
state	query	—	open/closed/all（默认 open）
head	query	—	过滤源分支（格式 user:branch）
base	query	—	过滤目标分支
sort	query	—	created/updated/popularity/long-running
per_page	query	—	每页数量（强制使用 100）

curl -s "https://api.github.com/repos/OWNER/REPO/pulls?state=open&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

27. 获取 PR

GET repos/{owner}/{repo}/pulls/{pull_number}

参数	位置	必填	说明
pull_number	path	✅	PR 编号

curl -s "https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

返回 mergeable（bool/null）和 mergeable_state（"clean"/"dirty"/"blocked"/"behind"/"unknown"）。mergeable 为 null 表示 GitHub 正在计算，需等待重试。

28. 创建 PR

POST repos/{owner}/{repo}/pulls

参数	位置	必填	说明
title	body	✅	PR 标题
head	body	✅	源分支（或 user:branch 跨 fork）
base	body	✅	目标分支
body	body	—	PR 描述（Markdown）
draft	body	—	是否为草稿 PR

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/pulls" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "PR 标题",
    "head": "feature-branch",
    "base": "main",
    "body": "PR 描述"
  }'

30. 合并 PR ⚠️ DESTRUCTIVE

PUT repos/{owner}/{repo}/pulls/{pull_number}/merge

参数	位置	必填	说明
commit_title	body	—	合并 commit 标题
commit_message	body	—	合并 commit 描述
merge_method	body	—	merge/squash/rebase
sha	body	—	PR HEAD SHA（确保合并时 PR 未变更）

curl -s -X PUT "https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/merge" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"merge_method": "squash", "commit_title": "feat: 新功能"}'

31. 列出 PR 文件

GET repos/{owner}/{repo}/pulls/{pull_number}/files

参数	位置	必填	说明
per_page	query	—	每页数量（强制使用 100）

curl -s "https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/files?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

38. 创建 PR Review

POST repos/{owner}/{repo}/pulls/{pull_number}/reviews

参数	位置	必填	说明
event	body	✅	APPROVE/REQUEST_CHANGES/COMMENT
body	body	—	Review 总结评论
comments	body	—	行内评论数组

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/reviews" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"event": "APPROVE", "body": "LGTM!"}'

42. 请求 Review

POST repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers

参数	位置	必填	说明
reviewers	body	—	用户名数组
team_reviewers	body	—	团队 slug 数组

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/pulls/PULL_NUMBER/requested_reviewers" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"reviewers": ["reviewer-username"]}'

---

Repos 操作（#46-#83）

46. 获取仓库

GET repos/{owner}/{repo}

参数	位置	必填	说明
owner	path	✅	仓库所有者
repo	path	✅	仓库名

curl -s "https://api.github.com/repos/OWNER/REPO" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

49. 创建仓库

POST user/repos

参数	位置	必填	说明
name	body	✅	仓库名
description	body	—	仓库描述
private	body	—	是否私有（默认 false）
auto_init	body	—	是否自动初始化 README
gitignore_template	body	—	.gitignore 模板（如 Go/Node）
license_template	body	—	License 模板（如 mit/apache-2.0）

curl -s -X POST "https://api.github.com/user/repos" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-repo",
    "description": "仓库描述",
    "private": false,
    "auto_init": true
  }'

53. Fork 仓库

POST repos/{owner}/{repo}/forks

参数	位置	必填	说明
organization	body	—	Fork 到指定组织（默认当前用户）
name	body	—	自定义 Fork 名称

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/forks" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{}'

55. 获取文件内容

GET repos/{owner}/{repo}/contents/{path}

参数	位置	必填	说明
path	path	✅	文件路径（如 src/main.go）
ref	query	—	分支/tag/commit SHA（默认默认分支）

curl -s "https://api.github.com/repos/OWNER/REPO/contents/README.md" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

返回 content（base64 编码）和 sha。解码内容：echo "$content" | base64 -d。目录返回文件对象数组。

56. 创建/更新文件

PUT repos/{owner}/{repo}/contents/{path}

参数	位置	必填	说明
path	path	✅	文件路径
message	body	✅	Commit message
content	body	✅	base64 编码的文件内容
sha	body	⚠️	更新已有文件时必填（从 GET 获取）
branch	body	—	目标分支（默认默认分支）

# 更新已有文件（需要 sha）
curl -s -X PUT "https://api.github.com/repos/OWNER/REPO/contents/path/to/file.txt" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "更新文件",
    "content": "SGVsbG8gV29ybGQ=",
    "sha": "CURRENT_FILE_SHA"
  }'

61. 列出 Release

GET repos/{owner}/{repo}/releases

参数	位置	必填	说明
per_page	query	—	每页数量（强制使用 100）

curl -s "https://api.github.com/repos/OWNER/REPO/releases?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

65. 创建 Release

POST repos/{owner}/{repo}/releases

参数	位置	必填	说明
tag_name	body	✅	Tag 名（如 v1.0.0）
name	body	—	Release 标题
body	body	—	Release 说明（Markdown）
draft	body	—	是否为草稿
prerelease	body	—	是否为预发布
target_commitish	body	—	创建 Tag 的目标（branch/SHA）
generate_release_notes	body	—	自动生成 Release Notes

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/releases" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_name": "v1.0.0",
    "name": "Release v1.0.0",
    "body": "## 变更内容\n- 新功能",
    "generate_release_notes": true
  }'

69. 上传 Release Asset

POST uploads.github.com/repos/{owner}/{repo}/releases/{release_id}/assets

参数	位置	必填	说明
release_id	path	✅	Release ID
name	query	✅	文件名
label	query	—	显示标签
Content-Type	header	✅	文件 MIME 类型

curl -s -X POST "https://uploads.github.com/repos/OWNER/REPO/releases/RELEASE_ID/assets?name=app.zip" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/zip" \
  --data-binary @app.zip

注意：域名是 uploads.github.com（不是 api.github.com），Content-Type 按文件实际类型设置。

---

Users 操作（#84-#95）

84. 获取认证用户

GET user

参数	位置	必填	说明
—	—	—	无参数

curl -s "https://api.github.com/user" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

86. 获取用户

GET users/{username}

参数	位置	必填	说明
username	path	✅	用户名

curl -s "https://api.github.com/users/USERNAME" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

90. 关注用户

PUT user/following/{username}

参数	位置	必填	说明
username	path	✅	要关注的用户名

curl -s -X PUT "https://api.github.com/user/following/USERNAME" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

成功返回 204（无 body）。

93. 添加 SSH Key

POST user/keys

参数	位置	必填	说明
title	body	✅	Key 标题
key	body	✅	SSH 公钥内容

curl -s -X POST "https://api.github.com/user/keys" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"title": "My SSH Key", "key": "ssh-ed25519 AAAA..."}'

---

Search 操作（#96-#101）

限流提醒：Search API 独立限流 30 req/min（见 §8.5）。批量搜索时注意间隔。

96. 搜索仓库

GET search/repositories

参数	位置	必填	说明
q	query	✅	搜索查询（支持限定词：language:go stars:>100 topic:cli）
sort	query	—	stars/forks/help-wanted-issues/updated
order	query	—	asc/desc
per_page	query	—	每页数量（最大 100）

curl -s "https://api.github.com/search/repositories?q=language:go+stars:>1000&sort=stars&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

返回 total_count + items 数组。items 中每个对象含 full_name、html_url、description 等。

97. 搜索 Issues/PRs

GET search/issues

参数	位置	必填	说明
q	query	✅	搜索查询（限定词：is:issue is:open repo:owner/repo label:bug）
sort	query	—	comments/reactions/created/updated
order	query	—	asc/desc
per_page	query	—	每页数量（最大 100）

curl -s "https://api.github.com/search/issues?q=is:issue+is:open+repo:cli/cli+label:bug&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

常用限定词：is:issue/is:pr、is:open/is:closed、repo:owner/repo、author:user、label:name、assignee:user。

98. 搜索代码

GET search/code

参数	位置	必填	说明
q	query	✅	搜索查询（限定词：filename:*.go repo:owner/repo path:src/）
sort	query	—	indexed（按索引日期）
order	query	—	asc/desc
per_page	query	—	每页数量（最大 100）

curl -s "https://api.github.com/search/code?q=handleError+repo:cli/cli+filename:*.go&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

代码搜索必须指定 repo:、org: 或 user: 限定词，否则返回 422。

99. 搜索 Commits

GET search/commits

参数	位置	必填	说明
q	query	✅	搜索查询（限定词：repo:owner/repo author:user）
sort	query	—	author-date/committer-date
per_page	query	—	每页数量

curl -s "https://api.github.com/search/commits?q=fix+repo:cli/cli&sort=author-date&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

100. 搜索用户

GET search/users

参数	位置	必填	说明
q	query	✅	搜索查询（限定词：type:user location:china language:go）
sort	query	—	followers/repositories/joined
per_page	query	—	每页数量

curl -s "https://api.github.com/search/users?q=type:user+language:go+followers:>100&sort=followers&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

101. 搜索 Topics

GET search/topics

参数	位置	必填	说明
q	query	✅	Topic 名称关键词
per_page	query	—	每页数量

curl -s "https://api.github.com/search/topics?q=machine-learning&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

---

Actions 操作（#102-#136）

102. 列出仓库 Workflows

GET repos/{owner}/{repo}/actions/workflows

参数	位置	必填	说明
per_page	query	—	每页数量（强制使用 100）

curl -s "https://api.github.com/repos/OWNER/REPO/actions/workflows?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

104. 触发 Workflow ⚠️ DESTRUCTIVE

POST repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches

参数	位置	必填	说明
workflow_id	path	✅	Workflow ID 或文件名（如 ci.yml）
ref	body	✅	目标分支/tag
inputs	body	—	Workflow 输入参数（key-value 对象）

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/actions/workflows/ci.yml/dispatches" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"ref": "main", "inputs": {"environment": "staging"}}'

成功返回 204（无 body）。不返回 run_id，需通过 workflow:trigger-workflow 流程追踪。

105. 列出 Workflow Runs

GET repos/{owner}/{repo}/actions/runs

参数	位置	必填	说明
status	query	—	completed/in_progress/queued/waiting 等
branch	query	—	过滤分支
event	query	—	触发事件（push/pull_request/workflow_dispatch 等）
per_page	query	—	每页数量（强制使用 100）

curl -s "https://api.github.com/repos/OWNER/REPO/actions/runs?status=completed&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

107. 获取 Run

GET repos/{owner}/{repo}/actions/runs/{run_id}

参数	位置	必填	说明
run_id	path	✅	Run ID

curl -s "https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

关键字段：status（queued/in_progress/completed）、conclusion（success/failure/cancelled/skipped）。

108. 取消 Run

POST repos/{owner}/{repo}/actions/runs/{run_id}/cancel

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID/cancel" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

109. 重新运行 Run

POST repos/{owner}/{repo}/actions/runs/{run_id}/rerun

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID/rerun" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

114. 列出 Run 的 Jobs

GET repos/{owner}/{repo}/actions/runs/{run_id}/jobs

参数	位置	必填	说明
filter	query	—	latest（仅最新尝试）/all
per_page	query	—	每页数量

curl -s "https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID/jobs?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

120. 下载 Artifact

GET repos/{owner}/{repo}/actions/artifacts/{artifact_id}/zip

curl -sL "https://api.github.com/repos/OWNER/REPO/actions/artifacts/ARTIFACT_ID/zip" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -o artifact.zip

返回 302 重定向到下载 URL，使用 -L 跟随重定向。

124. 创建/更新 Secret（需加密）

PUT repos/{owner}/{repo}/actions/secrets/{secret_name}

加密流程（必须先获取 public key）：

# 步骤 1：获取仓库 public key
curl -s "https://api.github.com/repos/OWNER/REPO/actions/secrets/public-key" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"
# 返回：{"key_id": "...", "key": "base64_public_key"}

# 步骤 2：使用 openssl 加密 Secret（无需 libsodium）
# 注意：GitHub 使用 libsodium sealed box 加密，openssl 不能直接替代
# 推荐方式：使用 Python 或 Node.js 的 tweetnacl 库
python3 -c "
import base64, sys
from nacl.public import SealedBox, PublicKey
public_key = base64.b64decode('BASE64_PUBLIC_KEY')
sealed_box = SealedBox(PublicKey(public_key))
encrypted = sealed_box.encrypt(b'SECRET_VALUE')
print(base64.b64encode(encrypted).decode())
"

# 步骤 3：创建/更新 Secret
curl -s -X PUT "https://api.github.com/repos/OWNER/REPO/actions/secrets/MY_SECRET" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"encrypted_value": "ENCRYPTED_BASE64", "key_id": "KEY_ID"}'

Secret 值必须使用 libsodium sealed box 加密。Python pynacl 或 Node.js tweetnacl 均可完成。

129. 创建 Variable

POST repos/{owner}/{repo}/actions/variables

参数	位置	必填	说明
name	body	✅	Variable 名称
value	body	✅	Variable 值（明文）

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/actions/variables" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"name": "ENV_NAME", "value": "production"}'

---

Orgs & Teams 操作（#137-#154）

137. 获取组织

GET orgs/{org}

curl -s "https://api.github.com/orgs/ORG_NAME" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

140. 列出组织成员

GET orgs/{org}/members

参数	位置	必填	说明
role	query	—	all/admin/member（默认 all）
per_page	query	—	每页数量（强制使用 100）

curl -s "https://api.github.com/orgs/ORG_NAME/members?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

146. 创建团队

POST orgs/{org}/teams

参数	位置	必填	说明
name	body	✅	团队名称
description	body	—	团队描述
privacy	body	—	secret（仅成员可见）/closed（组织内可见）
permission	body	—	pull/push/admin

curl -s -X POST "https://api.github.com/orgs/ORG_NAME/teams" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"name": "frontend-team", "description": "前端团队", "privacy": "closed"}'

150. 添加团队成员

PUT orgs/{org}/teams/{team_slug}/memberships/{username}

参数	位置	必填	说明
role	body	—	member/maintainer（默认 member）

curl -s -X PUT "https://api.github.com/orgs/ORG_NAME/teams/TEAM_SLUG/memberships/USERNAME" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"role": "member"}'

---

Commits & Checks 操作（#155-#168）

155. 列出 Commits

GET repos/{owner}/{repo}/commits

参数	位置	必填	说明
sha	query	—	分支名或 commit SHA
path	query	—	过滤修改了指定路径的 commit
author	query	—	过滤作者（GitHub 用户名或邮箱）
since	query	—	起始时间（ISO 8601）
until	query	—	截止时间（ISO 8601）
per_page	query	—	每页数量（强制使用 100）

curl -s "https://api.github.com/repos/OWNER/REPO/commits?sha=main&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

156. 获取 Commit

GET repos/{owner}/{repo}/commits/{ref}

curl -s "https://api.github.com/repos/OWNER/REPO/commits/COMMIT_SHA" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

返回 files 数组含每个变更文件的 filename/status/additions/deletions/patch。

157. 比较 Commits

GET repos/{owner}/{repo}/compare/{basehead}

参数	位置	必填	说明
basehead	path	✅	格式 base...head（如 main...feature）

curl -s "https://api.github.com/repos/OWNER/REPO/compare/main...feature-branch" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

160. 列出 Commit 的 Check Runs

GET repos/{owner}/{repo}/commits/{ref}/check-runs

curl -s "https://api.github.com/repos/OWNER/REPO/commits/COMMIT_SHA/check-runs?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

164. 获取 Combined Status

GET repos/{owner}/{repo}/commits/{ref}/status

curl -s "https://api.github.com/repos/OWNER/REPO/commits/COMMIT_SHA/status" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

返回 state（pending/success/error/failure）和 statuses 数组。

166. 创建 Commit Status

POST repos/{owner}/{repo}/statuses/{sha}

参数	位置	必填	说明
sha	path	✅	Commit SHA
state	body	✅	pending/success/error/failure
target_url	body	—	状态详情链接
description	body	—	状态描述
context	body	—	状态上下文标识（如 ci/build）

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/statuses/COMMIT_SHA" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "success",
    "target_url": "https://ci.example.com/build/123",
    "description": "Build passed",
    "context": "ci/build"
  }'

---

Activity 操作（#169-#180）

169. 列出通知

GET notifications

参数	位置	必填	说明
all	query	—	true 包含已读通知
participating	query	—	true 仅参与的
since	query	—	起始时间（ISO 8601）
per_page	query	—	每页数量（强制使用 100）

curl -s "https://api.github.com/notifications?all=false&per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

171. 标记通知已读

PUT notifications

参数	位置	必填	说明
last_read_at	body	—	标记此时间之前的通知为已读（ISO 8601，默认当前时间）

curl -s -X PUT "https://api.github.com/notifications" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"last_read_at": "2024-01-01T00:00:00Z"}'

175. Star 仓库

PUT user/starred/{owner}/{repo}

curl -s -X PUT "https://api.github.com/user/starred/OWNER/REPO" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

成功返回 204（无 body）。

177. 列出用户 Starred

GET users/{username}/starred

curl -s "https://api.github.com/users/USERNAME/starred?per_page=100" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

178. Watch 仓库

PUT repos/{owner}/{repo}/subscription

参数	位置	必填	说明
subscribed	body	—	是否订阅通知
ignored	body	—	是否忽略通知

curl -s -X PUT "https://api.github.com/repos/OWNER/REPO/subscription" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"subscribed": true, "ignored": false}'

---

Git Low-level 操作（#181-#190）

181. 创建 Blob

POST repos/{owner}/{repo}/git/blobs

参数	位置	必填	说明
content	body	✅	文件内容
encoding	body	—	utf-8（默认）或 base64

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/git/blobs" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"content": "文件内容", "encoding": "utf-8"}'

183. 创建 Tree

POST repos/{owner}/{repo}/git/trees

参数	位置	必填	说明
tree	body	✅	Tree 条目数组
base_tree	body	—	基础 tree SHA（增量更新时使用）

每个 tree 条目：

字段	必填	说明
path	✅	文件路径
mode	✅	100644（普通文件）/100755（可执行）/040000（目录）/160000（子模块）
type	✅	blob/tree/commit
sha	⚠️	Blob SHA（与 content 二选一）
content	⚠️	直接内联内容（与 sha 二选一）

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/git/trees" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "base_tree": "BASE_TREE_SHA",
    "tree": [
      {"path": "src/main.go", "mode": "100644", "type": "blob", "sha": "BLOB_SHA"}
    ]
  }'

185. 创建 Commit

POST repos/{owner}/{repo}/git/commits

参数	位置	必填	说明
message	body	✅	Commit message
tree	body	✅	Tree SHA
parents	body	✅	父 commit SHA 数组
author	body	—	作者信息 {name, email, date}

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/git/commits" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "feat: 通过 API 创建的 commit",
    "tree": "NEW_TREE_SHA",
    "parents": ["PARENT_COMMIT_SHA"]
  }'

187. 获取 Ref

GET repos/{owner}/{repo}/git/ref/{ref}

参数	位置	必填	说明
ref	path	✅	Ref 路径（如 heads/main、tags/v1.0）

curl -s "https://api.github.com/repos/OWNER/REPO/git/ref/heads/main" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json"

返回 object.sha 即为当前分支指向的 commit SHA。

188. 创建 Ref

POST repos/{owner}/{repo}/git/refs

参数	位置	必填	说明
ref	body	✅	Ref 全路径（如 refs/heads/new-branch）
sha	body	✅	指向的 commit SHA

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/git/refs" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"ref": "refs/heads/new-branch", "sha": "COMMIT_SHA"}'

189. 更新 Ref

PATCH repos/{owner}/{repo}/git/refs/{ref}

参数	位置	必填	说明
ref	path	✅	Ref 路径（如 heads/main）
sha	body	✅	新指向的 commit SHA
force	body	—	是否强制更新（非 fast-forward）

curl -s -X PATCH "https://api.github.com/repos/OWNER/REPO/git/refs/heads/main" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{"sha": "NEW_COMMIT_SHA"}'

---

Gists 操作（#191-#198）

193. 创建 Gist

POST gists

参数	位置	必填	说明
files	body	✅	文件对象 {"filename": {"content": "..."}}
description	body	—	Gist 描述
public	body	—	是否公开（默认 false）

curl -s -X POST "https://api.github.com/gists" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "代码片段",
    "public": false,
    "files": {
      "hello.py": {"content": "print(\"Hello World\")"}
    }
  }'

194. 更新 Gist

PATCH gists/{gist_id}

参数	位置	必填	说明
files	body	—	文件变更（content=null 删除文件，新 key 添加文件）
description	body	—	新描述

curl -s -X PATCH "https://api.github.com/gists/GIST_ID" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "files": {
      "hello.py": {"content": "print(\"Updated\")"},
      "new_file.txt": {"content": "新文件内容"}
    }
  }'

---

Deployments 操作（#199-#206）

201. 创建 Deployment

POST repos/{owner}/{repo}/deployments

参数	位置	必填	说明
ref	body	✅	部署的分支/tag/SHA
environment	body	—	环境名（如 production/staging）
description	body	—	部署描述
auto_merge	body	—	是否自动合并（默认 true）
required_contexts	body	—	必须通过的状态检查（空数组跳过检查）

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/deployments" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "main",
    "environment": "production",
    "description": "部署到生产环境",
    "required_contexts": []
  }'

205. 创建 Deployment Status

POST repos/{owner}/{repo}/deployments/{deployment_id}/statuses

参数	位置	必填	说明
state	body	✅	error/failure/inactive/in_progress/queued/pending/success
description	body	—	状态描述
environment_url	body	—	环境 URL
log_url	body	—	日志 URL

curl -s -X POST "https://api.github.com/repos/OWNER/REPO/deployments/DEPLOYMENT_ID/statuses" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "Accept: application/vnd.github+json" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "success",
    "description": "部署成功",
    "environment_url": "https://app.example.com"
  }'

---

§8 运维契约

8.1 HTTP 错误→AI 行为映射表

收到 API 错误时，AI 必须按以下表格执行对应行为：

HTTP 状态码	含义	AI 行为
400	Bad Request	检查请求体 JSON 语法和必填参数，对照 §7 参数表修正后重试
401	Unauthorized / Bad credentials	提示用户检查 Token 是否有效或已过期；绝不在输出中显示 Token 值
403（body 含 "secondary rate limit"）	次级限流	执行限流处理算法（见 §8.3），等待 retry-after 或指数退避后重试
403（body 含 "Resource not accessible"）	权限不足	告知用户：当前 Token 无权执行此操作。引导用户检查 Token scope 或仓库权限设置
403（其他）	禁止访问	检查 body 中的 message 字段，根据具体原因引导用户（如 "Repository access blocked" → 检查 IP 允许列表）
404	Not Found	验证 owner/repo/资源 ID 是否正确；检查仓库是否为 private（可能需要额外 scope）；提示用户确认资源是否存在
409	Conflict	存在并发修改冲突（如 merge conflict），报告具体冲突原因，由用户决定处理方式
422	Validation Failed	检查请求参数格式（如缺少必填字段、SHA 不匹配、branch 已存在等），解析 errors 数组获取详细原因，修正后重试
429	Rate Limited	执行限流处理算法（见 §8.3）；所有 HTTP 方法均可重试
500	Internal Server Error	仅对幂等方法（GET/DELETE）自动重试（最多 2 次，指数退避）；POST/PATCH/PUT 报告错误，由用户决定是否重试
502	Bad Gateway	同 500 处理策略
503	Service Unavailable	同 500 处理策略

403 三义歧义处理（关键）：收到 403 时，AI 必须先检查响应 body：

1. 包含 "secondary rate limit" → 等待重试（不是权限问题）
2. 包含 "Resource not accessible" → 权限不足（停止，引导用户）
3. 其他 → 读取 message 字段判断具体原因

8.2 Link 头分页契约（算法）

GitHub REST API 使用 Link Header 进行分页（不同于 Notion 的 has_more / next_cursor 模式）。

FUNCTION paginate(endpoint, params):
  all_results = []
  url = endpoint + "?" + urlencode(params) + "&per_page=100"

  LOOP:
    response = CALL GET url
    all_results.APPEND(response.body)

    link_header = response.headers["Link"]
    IF link_header CONTAINS rel="next" THEN
      url = EXTRACT url FROM link_header WHERE rel="next"
      GOTO LOOP
    ELSE
      RETURN all_results
    END IF

Link Header 解析规则（强制）：

1. 始终使用 per_page=100（GitHub 默认仅 30 条，会导致静默数据截断）
2. 解析 Link Header：格式为 <URL>; rel="next", <URL>; rel="last"，提取 rel="next" 对应的 URL
3. 禁止将部分结果当作完整结果呈现给用户 — 若存在 rel="next"，必须继续翻页或明确告知用户"还有更多数据"
4. 翻页完成后，告知用户"已获取全部 N 条结果"
5. bash 解析示例：

   # 从 Link Header 中提取 next URL
   next_url=$(echo "$link_header" | grep -oP '<\K[^>]+(?=>; rel="next")')
   

8.3 双路限流处理算法

GitHub 有两层限流机制：

Primary Rate Limit（主限流）：

• 认证用户：5,000 requests/hour
• 通过 x-ratelimit-remaining 和 x-ratelimit-reset Header 监控
• 触发时返回 HTTP 429

Secondary Rate Limit（次级限流）：

• 针对短时间内大量请求的额外保护
• 触发时返回 HTTP 403（body 含 "secondary rate limit"）
• 通常由并发请求或短时间内创建大量内容触发

FUNCTION handle_rate_limit(response, attempt):
  IF attempt > MAX_RETRIES(2) THEN
    FAIL "超过最大重试次数，请稍后再试"
  END IF

  # 检查是否为 429（主限流）
  IF response.status == 429 THEN
    IF response.headers["retry-after"] EXISTS THEN
      wait_seconds = response.headers["retry-after"]
    ELIF response.headers["x-ratelimit-reset"] EXISTS THEN
      wait_seconds = response.headers["x-ratelimit-reset"] - NOW_UNIX
    ELSE
      wait_seconds = MIN(1 * 2^attempt + random(0, 1), 60)
    END IF
  END IF

  # 检查是否为 403 次级限流
  IF response.status == 403 AND response.body CONTAINS "secondary rate limit" THEN
    IF response.headers["retry-after"] EXISTS THEN
      wait_seconds = response.headers["retry-after"]
    ELSE
      wait_seconds = MIN(60 * 2^attempt, 300)  # 次级限流等待更久
    END IF
  END IF

  SLEEP(MIN(wait_seconds, 300))
  RETRY request

x-ratelimit- Header 说明*：

Header	说明	示例
x-ratelimit-limit	每小时总配额	5000
x-ratelimit-remaining	当前窗口剩余配额	4999
x-ratelimit-reset	配额重置时间（Unix 时间戳）	1713456000
x-ratelimit-used	当前窗口已使用配额	1
x-ratelimit-resource	限流资源类型	core / search / graphql

主动预防：

• 每次请求后检查 x-ratelimit-remaining，若低于 100 则降低请求频率
• 若为 0，等待至 x-ratelimit-reset 时间点后再请求

8.4 通用约定

1. Base URL：https://api.github.com（所有端点都基于此地址）
2. API 版本：所有请求必须附带 X-GitHub-Api-Version: 2022-11-28 Header
3. Accept Header：所有请求建议附带 Accept: application/vnd.github+json
4. Content-Type：POST/PATCH/PUT 请求体为 JSON（application/json）；文件上传为 application/octet-stream 或 multipart/form-data
5. Token 传递：仅通过 Authorization: Bearer <token> Header 传递
6. ID 格式：GitHub 使用整数 ID（如 123456789），不同于 UUID 格式
7. 日期格式：ISO 8601（YYYY-MM-DDTHH:MM:SSZ）
8. 空响应：DELETE 和某些 PUT 操作成功返回 HTTP 204（无 body）
9. PowerShell 注意：irm 是 Invoke-RestMethod 别名；文件上传需用 curl.exe；续行符为反引号 ` 而非 \

8.5 Search API 独立限流说明

Search API 有独立的限流配额，不与核心 API 共享：

限制	值	说明
认证用户	30 requests/min	通过 x-ratelimit-resource: search 识别
未认证	10 requests/min	不适用（本 SKILL 始终使用 Token）

Search 限流处理：

• Search 限流通过 x-ratelimit-resource: search 区分
• 触发 429 后按 §8.3 算法处理，但等待时间通常以分钟为单位
• 建议：批量搜索时在每次请求间间隔 2-3 秒，主动避免触发限流
• Search 结果最多返回前 1,000 条匹配项（GitHub 硬限制），超出需用更精确的查询条件缩小范围

---

Source: 234194027-cpu/xianclaw — distributed by TomeVault.