github skill
- Repo stars 0
- Author repo skills-registry
- Domain
- DevOps
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 84 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Heavy
- Setup complexity
- Manual integration
- External API key
- Not required
- Operating systems
- Windows
- Runtime requirements
- Node.js · Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Env read
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# GitHub SKILL
## 初始化(必须首先执行)
1. 读取同目录下的 `SETUP_TOKEN.md`
2. 将 `<SCRIPT_PATH>` 替换为本文件所在目录的绝对路径
3. **每条 curl/API 命令中都必须内联获取 token**(因为每次命令是独立 shell,export 无法跨命令传递):
```bash
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 文档](https://docs.github.com/en/enterprise-server/rest) |
| GitHub Apps / Installation Token | 完全不同的认证流程(JWT + Installation Token),超出 OAuth2 scope | 参考 [GitHub Apps 文档](https://docs.github.com/en/apps) |
| OAuth 浏览器授权流程 | 需要浏览器交互(跳转授权页、处理回调),CLI 环境无法完成 | 参考 [GitHub OAuth 文档](https://docs.github.com/en/apps/oauth-apps) |
| gh CLI 命令封装 | gh 会持久化保存 Token,不符合 AI 代理安全要求 | 使用本 SKILL 提供的 curl 模板 |
| GraphQL API | 复杂度高,REST API 已覆盖绝大多数场景 | 参考 [GitHub GraphQL API 文档](https://docs.github.com/en/graphql) |
| Token 持久化存储 | AI 代理不保留跨会话状态,每次命令独立获取 Token | 使用 `get-token.sh` / `get-token.ps1` 动态获取 |
| Codespaces 管理 | 需要特殊 scope,场景极度垂直 | 参考 [Codespaces API 文档](https://docs.github.com/en/rest/codespaces) |
| Billing 计费操作 | AI 代理无需操作计费数据,风险高 | 参考 [Billing API 文档](https://docs.github.com/en/rest/billing) |
| Migration 迁移操作 | 一次性高风险操作,不适合 AI 代理自动执行 | 参考 [Migration API 文档](https://docs.github.com/en/rest/migrations) |
**拒绝话术模板**:
> "本 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 | 获取标签 | `GET` | `repos/{owner}/{repo}/labels/{name}` | 获取单个标签 |
| 14 | 创建标签 | `POST` | `repos/{owner}/{repo}/labels` | 创建新标签 |
| 15 | 更新标签 | `PATCH` | `repos/{owner}/{repo}/labels/{name}` | 更新标签 |
| 16 | 删除标签 | `DELETE` | `repos/{owner}/{repo}/labels/{name}` | 删除标签 |
| 17 | 列出 Issue 标签 | `GET` | `repos/{owner}/{repo}/issues/{issue_number}/labels` | 列出 Issue 上的标签 |
| 18 | 添加 Issue 标签 | `POST` | `repos/{owner}/{repo}/issues/{issue_number}/labels` | 添加标签到 Issue |
| 19 | 移除 Issue 标签 | `DELETE` | `repos/{owner}/{repo}/issues/{issue_number}/labels/{name}` | 从 Issue 移除标签 |
| 20 | 列出 Assignees | `GET` | `repos/{owner}/{repo}/assignees` | 列出仓库可分配人员 |
| 21 | 添加 Assignees | `POST` | `repos/{owner}/{repo}/issues/{issue_number}/assignees` | 添加分配人到 Issue |
| 22 | 移除 Assignees | `DELETE` | `repos/{owner}/{repo}/issues/{issue_number}/assignees` | 从 Issue 移除分配人 |
| 23 | 列出仓库里程碑 | `GET` | `repos/{owner}/{repo}/milestones` | 列出所有里程碑 |
| 24 | 创建里程碑 | `POST` | `repos/{owner}/{repo}/milestones` | 创建新里程碑 |
| 25 | 更新里程碑 | `PATCH` | `repos/{owner}/{repo}/milestones/{milestone_number}` | 更新里程碑 |
### 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 详情 |
| 38 | 创建 PR Review | `POST` | `repos/{owner}/{repo}/pulls/{pull_number}/reviews` | 创建 Review(APPROVE/REQUEST_CHANGES/COMMENT) |
| 39 | 提交 PR Review | `POST` | `repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/events` | 提交待处理的 Review |
| 40 | 删除 PR Review | `DELETE` | `repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}` | 删除待处理的 Review |
| 41 | 列出 Requested Reviewers | `GET` | `repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers` | 列出被请求的审查人 |
| 42 | 请求 Review | `POST` | `repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers` | 请求用户/团队审查 PR |
| 43 | 移除 Review 请求 | `DELETE` | `repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers` | 取消审查请求 |
| 44 | 更新 PR 分支 | `PUT` | `repos/{owner}/{repo}/pulls/{pull_number}/update-branch` | 将 base 分支合并到 PR 分支 |
| 45 | 列出 Issue 评论(PR 用) | `GET` | `repos/{owner}/{repo}/issues/{pull_number}/comments` | PR 的 Issue 级评论(非 diff 评论) |
### 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` | `repos/{owner}/{repo}/branches` | 列出仓库分支 |
| 60 | 获取分支 | `GET` | `repos/{owner}/{repo}/branches/{branch}` | 获取分支详情(含保护状态) |
| 61 | 列出 Release | `GET` | `repos/{owner}/{repo}/releases` | 列出仓库 Release |
| 62 | 获取 Release | `GET` | `repos/{owner}/{repo}/releases/{release_id}` | 获取 Release 详情 |
| 63 | 获取最新 Release | `GET` | `repos/{owner}/{repo}/releases/latest` | 获取最新 Release |
| 64 | 按 Tag 获取 Release | `GET` | `repos/{owner}/{repo}/releases/tags/{tag}` | 按 Tag 名获取 Release |
| 65 | 创建 Release | `POST` | `repos/{owner}/{repo}/releases` | 创建新 Release |
| 66 | 更新 Release | `PATCH` | `repos/{owner}/{repo}/releases/{release_id}` | 更新 Release |
| 67 | 删除 Release ⚠️ | `DELETE` | `repos/{owner}/{repo}/releases/{release_id}` | 删除 Release(不可逆) |
| 68 | 列出 Release Assets | `GET` | `repos/{owner}/{repo}/releases/{release_id}/assets` | 列出 Release 附件 |
| 69 | 上传 Release Asset | `POST` | `uploads.github.com/repos/{owner}/{repo}/releases/{release_id}/assets` | 上传附件(Content-Type 按文件类型) |
| 70 | 获取 Release Asset | `GET` | `repos/{owner}/{repo}/releases/assets/{asset_id}` | 获取附件详情 |
| 71 | 删除 Release Asset | `DELETE` | `repos/{owner}/{repo}/releases/assets/{asset_id}` | 删除附件 |
| 72 | 列出协作者 | `GET` | `repos/{owner}/{repo}/collaborators` | 列出仓库协作者 |
| 73 | 添加协作者 | `PUT` | `repos/{owner}/{repo}/collaborators/{username}` | 添加协作者(发送邀请) |
| 74 | 移除协作者 | `DELETE` | `repos/{owner}/{repo}/collaborators/{username}` | 移除协作者 |
| 75 | 列出 Topics | `GET` | `repos/{owner}/{repo}/topics` | 获取仓库 Topic |
| 76 | 替换 Topics | `PUT` | `repos/{owner}/{repo}/topics` | 替换仓库全部 Topic |
| 77 | 列出语言 | `GET` | `repos/{owner}/{repo}/languages` | 获取仓库语言统计 |
| 78 | 列出 Tags | `GET` | `repos/{owner}/{repo}/tags` | 列出仓库 Tag |
| 79 | 获取 License | `GET` | `repos/{owner}/{repo}/license` | 获取仓库 License |
| 80 | 列出 Webhooks | `GET` | `repos/{owner}/{repo}/hooks` | 列出仓库 Webhook |
| 81 | 创建 Webhook | `POST` | `repos/{owner}/{repo}/hooks` | 创建 Webhook |
| 82 | 列出 Deploy Keys | `GET` | `repos/{owner}/{repo}/keys` | 列出仓库部署密钥 |
| 83 | 添加 Deploy Key | `POST` | `repos/{owner}/{repo}/keys` | 添加部署密钥 |
### 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` | 删除 Run 日志 |
| 114 | 列出 Run 的 Jobs | `GET` | `repos/{owner}/{repo}/actions/runs/{run_id}/jobs` | 列出 Run 中的所有 Job |
| 115 | 获取 Job | `GET` | `repos/{owner}/{repo}/actions/jobs/{job_id}` | 获取 Job 详情(含 steps) |
| 116 | 下载 Job 日志 | `GET` | `repos/{owner}/{repo}/actions/jobs/{job_id}/logs` | 下载 Job 日志(302 重定向) |
| 117 | 列出 Run 的 Artifacts | `GET` | `repos/{owner}/{repo}/actions/runs/{run_id}/artifacts` | 列出 Run 产出的 Artifacts |
| 118 | 列出仓库 Artifacts | `GET` | `repos/{owner}/{repo}/actions/artifacts` | 列出仓库所有 Artifacts |
| 119 | 获取 Artifact | `GET` | `repos/{owner}/{repo}/actions/artifacts/{artifact_id}` | 获取 Artifact 详情 |
| 120 | 下载 Artifact | `GET` | `repos/{owner}/{repo}/actions/artifacts/{artifact_id}/{archive_format}` | 下载 Artifact(ZIP,302 重定向) |
| 121 | 删除 Artifact | `DELETE` | `repos/{owner}/{repo}/actions/artifacts/{artifact_id}` | 删除 Artifact |
| 122 | 列出仓库 Secrets | `GET` | `repos/{owner}/{repo}/actions/secrets` | 列出仓库 Actions Secrets |
| 123 | 获取 Secret | `GET` | `repos/{owner}/{repo}/actions/secrets/{secret_name}` | 获取 Secret 元数据(不含值) |
| 124 | 创建/更新 Secret ⚠️ | `PUT` | `repos/{owner}/{repo}/actions/secrets/{secret_name}` | 创建或更新 Secret(需加密) |
| 125 | 删除 Secret ⚠️ | `DELETE` | `repos/{owner}/{repo}/actions/secrets/{secret_name}` | 删除 Secret |
| 126 | 获取仓库 Public Key | `GET` | `repos/{owner}/{repo}/actions/secrets/public-key` | 获取用于加密 Secret 的公钥 |
| 127 | 列出仓库 Variables | `GET` | `repos/{owner}/{repo}/actions/variables` | 列出仓库 Actions Variables |
| 128 | 获取 Variable | `GET` | `repos/{owner}/{repo}/actions/variables/{name}` | 获取 Variable 值 |
| 129 | 创建 Variable | `POST` | `repos/{owner}/{repo}/actions/variables` | 创建 Variable |
| 130 | 更新 Variable | `PATCH` | `repos/{owner}/{repo}/actions/variables/{name}` | 更新 Variable |
| 131 | 删除 Variable | `DELETE` | `repos/{owner}/{repo}/actions/variables/{name}` | 删除 Variable |
| 132 | 列出 Environment Secrets | `GET` | `repos/{owner}/{repo}/environments/{env}/secrets` | 列出环境 Secrets |
| 133 | 列出 Environment Variables | `GET` | `repos/{owner}/{repo}/environments/{env}/variables` | 列出环境 Variables |
| 134 | 列出仓库 Environments | `GET` | `repos/{owner}/{repo}/environments` | 列出仓库 Environments |
| 135 | 获取 Environment | `GET` | `repos/{owner}/{repo}/environments/{env}` | 获取 Environment 详情 |
| 136 | 创建/更新 Environment | `PUT` | `repos/{owner}/{repo}/environments/{env}` | 创建或更新 Environment |
### 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}` | 添加团队成员 |
| 151 | 移除团队成员 | `DELETE` | `orgs/{org}/teams/{team_slug}/memberships/{username}` | 移除团队成员 |
| 152 | 列出团队仓库 | `GET` | `orgs/{org}/teams/{team_slug}/repos` | 列出团队管理的仓库 |
| 153 | 添加团队仓库 | `PUT` | `orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}` | 将仓库添加到团队 |
| 154 | 列出组织 Secrets | `GET` | `orgs/{org}/actions/secrets` | 列出组织级 Secrets |
### 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` | `repos/{owner}/{repo}/statuses/{sha}` | 创建 Commit 状态 |
| 167 | 列出 PR 的 Commit Statuses | `GET` | `repos/{owner}/{repo}/commits/{ref}/statuses` | 获取 PR HEAD 的状态 |
| 168 | 获取 Check Suite | `GET` | `repos/{owner}/{repo}/check-suites/{check_suite_id}` | 获取 Check Suite 详情 |
### 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}` | 返回 base64 编码内容;目录返回文件列表 |
| 更新文件 | workflow:update-file | 先 GET 获取 SHA → 再 PUT 带 SHA;见 §5.2 |
| 创建 Release | #65 `POST repos/{owner}/{repo}/releases` | 需指定 tag_name;可自动从 tag 创建 |
| 上传 Release 附件 | workflow:upload-release-asset | 用 uploads.github.com 域名;见 §5.2 |
| 搜索仓库 | #96 `GET search/repositories` | q 参数支持 `language:go stars:>100` 等限定词 |
| 搜索 Issue/PR | #97 `GET search/issues` | q 参数支持 `is:issue is:open repo:owner/repo` 等 |
| 搜索代码 | #98 `GET search/code` | q 参数支持 `filename:*.go path:src/` 等 |
| 搜索后操作 | workflow:search-then-act | 搜索 → 提取 ID → 调用操作接口;见 §5.2 |
| 获取当前用户 | #84 `GET user` | 确认认证身份 |
| 查看用户资料 | #86 `GET users/{username}` | 公开信息,无需特殊权限 |
| 查看 Workflow 列表 | #102 `GET .../actions/workflows` | 返回 workflow 文件名和 ID |
| 触发 Workflow | workflow:trigger-workflow | dispatch → 等待 → poll;见 §5.2 |
| 查看 Run 状态 | #107 `GET .../actions/runs/{run_id}` | 返回 status/conclusion |
| 取消运行中的 Run | #108 `POST .../actions/runs/{run_id}/cancel` | 仅对 in_progress/queued 有效 |
| 重新运行 | #109 `POST .../actions/runs/{run_id}/rerun` | 重新运行全部 Job |
| 管理 Secrets | #124 `PUT .../actions/secrets/{name}` | 需先获取 public key 并加密 |
| 管理 Variables | #129 `POST .../actions/variables` | 直接传明文值(不需要加密) |
| 查看组织信息 | #137 `GET orgs/{org}` | 公开信息 |
| 查看组织成员 | #140 `GET orgs/{org}/members` | 需组织访问权限 |
| 管理团队 | #146 `POST orgs/{org}/teams` | 创建/管理团队需 admin 权限 |
| 查看 Commit 详情 | #156 `GET repos/{owner}/{repo}/commits/{ref}` | 含文件变更列表 |
| 比较两个 Commit | #157 `GET .../compare/{base}...{head}` | 返回 diff 和文件变更 |
| 查看 Check Run 状态 | #160 `GET .../commits/{ref}/check-runs` | CI/CD 检查结果 |
| 创建 Commit Status | #166 `POST .../statuses/{sha}` | state: pending/success/error/failure |
| 查看通知 | #169 `GET notifications` | 认证用户的通知收件箱 |
| 标记通知已读 | #171 `PUT notifications` | 标记所有为已读 |
| Star 仓库 | #175 `PUT user/starred/{owner}/{repo}` | 返回 204 |
| Watch 仓库 | #178 `PUT .../subscription` | 设置订阅级别 |
| 通过 API 创建 Commit | workflow:create-commit-via-api | blob→tree→commit→ref 5 步;见 §5.2 |
| 创建/管理 Gist | #193 `POST gists` | 支持多文件 |
| 创建 Deployment | #201 `POST .../deployments` | 触发部署流程 |
| 更新 Deployment 状态 | #205 `POST .../deployments/{id}/statuses` | state: success/failure/error/inactive 等 |
### 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 模板**
```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 模板**
```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 格式模板](#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**) |
```bash
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 编号 |
```bash
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 | — | 里程碑编号(整数) |
```bash
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 | — | 替换全部分配人 |
```bash
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` |
```bash
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) |
```bash
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 | — | 标签描述 |
```bash
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"]` |
```bash
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"]` |
```bash
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**) |
```bash
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 编号 |
```bash
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 |
```bash
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 未变更) |
```bash
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**) |
```bash
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 | — | 行内评论数组 |
```bash
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 数组 |
```bash
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 | ✅ | 仓库名 |
```bash
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`) |
```bash
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 名称 |
```bash
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(默认默认分支) |
```bash
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 | — | 目标分支(默认默认分支) |
```bash
# 更新已有文件(需要 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**) |
```bash
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 |
```bash
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 类型 |
```bash
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`
| 参数 | 位置 | 必填 | 说明 |
|------|------|------|------|
| — | — | — | 无参数 |
```bash
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 | ✅ | 用户名 |
```bash
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 | ✅ | 要关注的用户名 |
```bash
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 公钥内容 |
```bash
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) |
```bash
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) |
```bash
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) |
```bash
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 | — | 每页数量 |
```bash
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 | — | 每页数量 |
```bash
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 | — | 每页数量 |
```bash
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**) |
```bash
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 对象) |
```bash
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**) |
```bash
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 |
```bash
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`
```bash
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`
```bash
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 | — | 每页数量 |
```bash
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`
```bash
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):
```bash
# 步骤 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 值(明文) |
```bash
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}`
```bash
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**) |
```bash
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` |
```bash
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) |
```bash
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**) |
```bash
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}`
```bash
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`) |
```bash
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`
```bash
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`
```bash
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`) |
```bash
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**) |
```bash
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,默认当前时间) |
```bash
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}`
```bash
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`
```bash
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 | — | 是否忽略通知 |
```bash
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` |
```bash
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 二选一) |
```bash
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}` |
```bash
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`) |
```bash
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 |
```bash
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) |
```bash
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) |
```bash
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 | — | 新描述 |
```bash
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 | — | 必须通过的状态检查(空数组跳过检查) |
```bash
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 |
```bash
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 解析示例**:
```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](https://github.com/234194027-cpu/xianclaw) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
Sections and files
Listed in source order.
sections -> See the original source for section headings
terms -> bash · PowerShell
files/cmd -> SETUP_TOKEN.md · <SCRIPT_PATH> · get-token.sh · get-token.ps1 · $(bash '<SCRIPT_PATH>/get-token.sh') · $token = & "<SCRIPT_PATH>\get-token.ps1" · $token · DELETE /repos/{owner}/{repo}
body sha256 -> c10e8fdd30ef