全功能GitHub API集成工具,含GraphQL、批量操作、Webhook管理、Actions API与组织管理,适合企业级集成场景。
GitHub API工具包(专业版)
功能概述
GitHub API工具包(专业版)是一项面向实际任务的技能,主要用于GraphQL API;GraphQL相比REST的优势: 一次查询获取关联数据,减少请求次数;
核心要点
- GraphQL查询模板库;
- 处理 : 按照skill规范执行GraphQL API操作,遵循单一意图原则;
- 输出 : 返回GraphQL API的执行结果,包含操作状态和输出数据;
使用与执行
### 批量操作;批量操作安全机制;预演模式 : --dry-run。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。从功能定位来看,该技能强调把分散的操作要求整理成清晰、可复用的处理流程,使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。
结果检查与注意事项
实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;涉及批量任务时,还应保存进度,避免中断后重复操作。该技能适合用于一次性任务,也可以接入自动化工作流,与其他技能或上层代理配合完成更完整的业务链路;在组合使用时,应明确每一步的输入输出关系,并避免不同步骤之间出现参数冲突。
GitHub API工具包(专业版)
核心能力
GraphQL API
GraphQL相比REST的优势: 一次查询获取关联数据,减少请求次数:
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN"
-H "Content-Type: application/json"
-d '{
"query": "query { repository(owner: "owner", name: "repo") { issues(first: 10, states: OPEN) { totalCount nodes { number title labels(first: 5) { nodes { name } } } } pullRequests(first: 10, states: OPEN) { totalCount } releases(first: 3) { nodes { tagName publishedAt } } } }"
}'
https://api.相关技术文档
GraphQL查询模板库:
query teamContributions($logins: [String!]!, $since: DateTime!) {
users(filter: {logins: $logins}) {
login
contributionsCollection(from: $since) {
pullRequestContributions(first: 100) {
totalCount
nodes {
pullRequest {
repository { nameWithOwner }
state
additions
deletions
mergedAt
}
}
}
issueContributions(first: 100) {
totalCount
}
}
}
}
query dependencyGraph($owner: String!, $name: String!) {
repository(owner: $owner, name: $name) {
dependencyGraphManifests(first: 50) {
nodes {
filename
dependencies(first: 100) {
nodes {
packageManager
packageName
requirements
}
}
}
}
}
}
处理: 按照skill规范执行GraphQL API操作,遵循单一意图原则。 输出: 返回GraphQL API的执行结果,包含操作状态和输出数据。### 批量操作
gh-api-toolkit batch-create-issues
--repo owner/repo
--input issues.csv
--fields title,body,labels
--rate-limit 30/min
gh-api-toolkit batch-update-repos
--repos "repo1,repo2,repo3"
--settings '{"has_issues":true,"has_wiki":false}'
gh-api-toolkit batch-add-collaborators
--repo owner/repo
--users "alice,bob,carol"
--permission push
gh-api-toolkit batch-archive-repos
--org my-org
--filter "inactive:>180d"
--dry-run
批量操作安全机制:
预演模式:
--dry-run预览变更,不实际执行速率控制: 自动遵守API限速,可配置QPS
断点续传: 失败时记录进度,支持从断点恢复
回滚支持: 生成反向操作脚本,支持撤销
进度报告: 实时显示进度与成功/失败计数
执行
GitHub Actions API操作,处理输入数据并返回结果验证执行结果,确认输出符合预期格式
参考
GitHub Actions API相关配置参数进行设置
Webhook管理
curl -H "Authorization: Bearer $GITHUB_TOKEN"
https://api.相关技术文档
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN"
-H "Content-Type: application/json"
-d '{
"config": {
"url": "https://hooks.example.com/github",
"content_type": "json",
"secret": "'$WEBHOOK_SECRET'"
},
"events": ["issues", "pull_request", "push", "release"],
"active": true
}'
https://api.相关技术文档
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN"
https://api.相关技术文档
curl -X DELETE -H "Authorization: Bearer $GITHUB_TOKEN"
https://api.相关技术文档
支持的事件类型:
| 事件类别 | 事件 | 说明 |
|---|---|---|
| 仓库 | push, create, delete, fork, public | 仓库级别事件 |
| Issue | issues, issue_comment, label | Issue相关事件 |
| PR | pull_request, pull_request_review | PR相关事件 |
| Release | release, deployment | 发布相关事件 |
| Actions | workflow_run, workflow_job | 工作流事件 |
| 组织 | organization, member, team | 组织事件 |
| 安全 | security_advisory, secret_scanning_alert | 安全事件 |
GitHub Actions API
curl -H "Authorization: Bearer $GITHUB_TOKEN"
https://api.相关技术文档
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN"
-H "Content-Type: application/json"
-d '{"ref":"main","inputs":{"environment":"staging"}}'
https://api.相关技术文档
curl -H "Authorization: Bearer $GITHUB_TOKEN"
"https://api.相关技术文档
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN"
https://api.相关技术文档
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN"
https://api.相关技术文档
curl -L -H "Authorization: Bearer $GITHUB_TOKEN"
-o artifact.zip
https://api.相关技术文档
输出: 返回GitHub Actions API的执行结果,包含操作状态和输出数据。
- 执行
GitHub Actions API操作,处理输入数据并返回结果 - 验证执行结果,确认输出符合预期格式
- 异常时参考错误处理章节进行恢复
- 关键参数:
github_actions_api选项 - 处理流程: 接收输入 -> 执行GitHub Actions API -> 返回结果
- 输入: 用户提供GitHub Actions API所需的参数和指令
- 输出: 返回GitHub Actions API的执行结果,包含操作状态和输出数据
组织与团队管理
curl -H "Authorization: Bearer $GITHUB_TOKEN"
"https://api.相关技术文档
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN"
-H "Content-Type: application/json"
-d '{"name":"backend-team","description":"后端团队","privacy":"closed"}'
https://api.相关技术文档
curl -X PUT -H "Authorization: Bearer $GITHUB_TOKEN"
-d '{"role":"member"}'
https://api.相关技术文档
curl -X PUT -H "Authorization: Bearer $GITHUB_TOKEN"
-d '{"permission":"push"}'
https://api.相关技术文档
curl -H "Authorization: Bearer $GITHUB_TOKEN"
https://api.相关技术文档
输入: 用户提供组织与团队管理所需的指令和必要参数。 处理: 按照skill规范执行组织与团队管理操作,遵循单一意图原则。 输出: 返回组织与团队管理的执行结果,包含操作状态和输出数据。### 高级搜索
curl -H "Authorization: Bearer $GITHUB_TOKEN" "https://api.相关技术文档 curl -H "Authorization: Bearer $GITHUB_TOKEN" "https://api.相关技术文档 curl -H "Authorization: Bearer $GITHUB_TOKEN" "https://api.相关技术文档 curl -H "Authorization: Bearer $GITHUB_TOKEN" "https://api.相关技术文档
- 执行
组织与团队管理操作,处理输入数据并返回结果 - 验证执行结果,确认输出符合预期格式
- 异常时参考错误处理章节进行恢复
- 关键参数:
组织与团队管理选项
能力覆盖范围
本skill还覆盖以下能力场景: 全功能、集成工具、与组织管理、适合企业级集成场、工具包、专业版、是企业级、在免费版、基础能力上、组织与团队管理等、高级能力、核心能力、高效关联查询、支持复杂分页、批量创建、删除资源、含速率控制与回滚、订阅事件、配置回调、测试与调试、工作流管理、运行控制、产物下载、成员管理。这些能力在上述核心功能中均有对应处理逻辑。
适用场景
场景1 -企业级仓库群批量管理
用户意图: "组织有50个仓库,需要统一更新设置并添加协作者。"
实施方案:
- 导出仓库列表(
gh-api-toolkit list-repos --org my-org) - 准备设置变更JSON与协作者列表
- 使用
--dry-run预演 - 执行
batch-update-repos与batch-add-collaborators - 生成变更报告
场景2 -DevOps平台集成
用户意图: "自建DevOps平台需要深度集成GitHub,包括事件订阅与工作流控制。"
实施方案:
- 配置Webhook订阅
push、pull_request、workflow_run事件 - 平台接收Webhook,触发对应流水线
- 通过Actions API触发/取消/重跑工作流
- 使用GraphQL聚合多仓库状态展示
场景3 -组织权限治理
用户意图: "审计组织权限,清理离职成员,调整团队结构。"
实施方案:
gh-api-toolkit audit-members --org my-org导出成员清单- 对比HR系统,标记离职成员
batch-remove-members移除离职成员- 调整团队结构,重新分配仓库权限
- 生成权限变更报告
场景4 -数据分析与BI
用户意图: "要做团队贡献分析,从GitHub拉取数据到BI平台。"
实施方案:
- 使用GraphQL查询团队贡献(一次查询获取多维度数据)
- 按周/月聚合PR、Issue、提交数据
- 导出为CSV/JSON,导入BI平台
- 设置定时任务,每日增量同步
使用流程
第1步:安装专业版工具
pip install gh-api-toolkit[pro] gh-api-toolkit version export GITHUB_TOKEN="ghp_your_token" gh-api-toolkit auth verify
第2步:GraphQL初体验
gh-api-toolkit graphql run --template repo_summary --vars '{"owner":"my-org","name":"my-repo"}'
gh-api-toolkit graphql run --query 'query { viewer { login repositories(first: 5) { nodes { name } } } }'
第3步:批量操作
cat > issues.csv << 'EOF' title,body,labels "Bug 1","描述1","bug" "Bug 2","描述2","bug" "Feature 1","描述3","enhancement" EOF gh-api-toolkit batch-create-issues --repo owner/repo --input issues.csv --dry-run gh-api-toolkit batch-create-issues --repo owner/repo --input issues.csv
第4步:配置Webhook
gh-api-toolkit webhook add --repo owner/repo --url "https://hooks.example.com/github" --events "issues,pull_request,push" --secret "$WEBHOOK_SECRET" gh-api-toolkit webhook test --repo owner/repo --event "issues"
命令参数说明
--template: 命令参数,用于指定操作选项-L: 命令参数,用于指定操作选项--permission: 命令参数,用于指定操作选项--rate-limit: 命令参数,用于指定操作选项-failed-jobs: 命令参数,用于指定操作选项
命令参数说明
-Type: 命令参数,用于指定操作选项-L: 命令参数,用于指定操作选项--fields: 命令参数,用于指定操作选项--vars: 命令参数,用于指定操作选项--settings: 命令参数,用于指定操作选项
命令参数说明
-H: 命令参数,用于指定操作选项--users: 命令参数,用于指定操作选项--events: 命令参数,用于指定操作选项--event: 命令参数,用于指定操作选项-L: 命令参数,用于指定操作选项
命令参数说明
-L: 命令参数,用于指定操作选项--query: 命令参数,用于指定操作选项--filter: 命令参数,用于指定操作选项-Type: 命令参数,用于指定操作选项-H: 命令参数,用于指定操作选项
命令参数说明
-H: 命令参数,用于指定操作选项-L: 命令参数,用于指定操作选项-Type: 命令参数,用于指定操作选项-archive-repos: 命令参数,用于指定操作选项-X: 命令参数,用于指定操作选项
命令参数说明
-X: 命令参数,用于指定操作选项-create-issues: 命令参数,用于指定操作选项-L: 命令参数,用于指定操作选项-H: 命令参数,用于指定操作选项-Type: 命令参数,用于指定操作选项
命令参数说明
-Type: 命令参数,用于指定操作选项-L: 命令参数,用于指定操作选项-H: 命令参数,用于指定操作选项-X: 命令参数,用于指定操作选项
命令参数说明
-Type: 命令参数,用于指定操作选项-H: 命令参数,用于指定操作选项-X: 命令参数,用于指定操作选项-L: 命令参数,用于指定操作选项
命令参数说明
-H: 命令参数,用于指定操作选项-X: 命令参数,用于指定操作选项-Type: 命令参数,用于指定操作选项-L: 命令参数,用于指定操作选项
输入格式
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| content | string | 是 | 相关说明 |
| content | string | 否 | 相关说明, 默认: 全部维度 |
| strict_level | string | 否 | 审查严格度, 可选: strict/normal/loose, 默认: normal |
输出格式
{
"success": true,
"data": {
"overall_grade": "A",
"total_score": 92,
"max_score": 100,
"summary": "处理完成",
"details": [
{
"item": "代码风格",
"status": "pass",
"score": 95,
"comment": "符合规范"
},
{
"item": "安全合规",
"status": "warn",
"score": 80,
"comment": "符合规范"
}
],
"improvements": [
{
"priority": "high",
"suggestion": "建议优化",
"expected_gain": "+5分"
},
{
"priority": "medium",
"suggestion": "建议优化",
"expected_gain": "+3分"
}
]
},
"error": null
}
异常处理
| 错误场景 | 原因 | 处理方式 |
|---|---|---|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,参考国内替代方案 |
依赖说明
运行环境
- Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
- 操作系统: Windows / macOS / Linux
- 网络: 可访问GitHub API
- Python: 3.8+(运行gh-api-toolkit CLI)
第三方依赖
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---|---|---|---|
| gh-api-toolkit[pro] | CLI工具 | 必需 | pip install gh-api-toolkit[pro] |
| curl | 命令行工具 | 必需 | 系统自带 |
| requests | Python库 | 必需 | 随gh-api-toolkit安装 |
| gql | Python库 | 必需 | 随gh-api-toolkit安装(GraphQL客户端) |
| GitHub账号 | 在线服务 | 必需 | 注册GitHub账号并生成PAT或App |
| LLM API | API | 必需 | 由Agent平台内置LLM提供 |
API Key 配置
- GitHub Token: 通过环境变量
GITHUB_TOKEN配置,禁止硬编码 - Webhook Secret: 通过环境变量
WEBHOOK_SECRET配置 - GitHub App私钥: 存储于
~/.gh-api-toolkit/app-private-key.pem(权限600) - Token权限: 根据场景选择scope,企业场景推荐使用GitHub App
- Token轮换: PAT每90天轮换,App token自动过期
- 禁止: 在SKILL.md或脚本中硬编码任何Token或私钥
可用性分类
- 分类: MD+EXEC+CLI+API(Markdown指令+命令行工具+REST/GraphQL API)
- 说明: 基于Markdown的AI Skill,,核心功能通过gh-api-toolkit CLI或直接API调用
案例展示
专业版配置文件
{
"edition": "pro",
"auth": {
"token_env": "GITHUB_TOKEN",
"default_scope": ["repo", "workflow", "read:org", "admin:org_hook", "admin:repo_hook"]
},
"graphql": {
"endpoint": "https://api.相关技术文档
"timeout": 30,
"complexity_limit": 500000,
"cache_ttl": 300
},
"batch": {
"rate_limit_qps": 10,
"max_retries": 3,
"checkpoint_interval": 10,
"dry_run_by_default": true
},
"webhook": {
"default_events": ["issues", "pull_request", "push"],
"secret_env": "WEBHOOK_SECRET",
"retry_count": 3
},
"actions": {
"default_ref": "main",
"artifact_retention": 90
}
}
批量操作脚本示例
from gh_api_toolkit import GitHubAPI, BatchProcessor
api = GitHubAPI(token=os.environ['GITHUB_TOKEN'])
issues = [
{"title": f"任务{i}", "body": f"任务{i}的描述", "labels": ["task"]}
for i in range(1, 101)
]
processor = BatchProcessor(api, rate_limit_qps=10)
results = processor.batch_create_issues(
owner="my-org",
repo="my-repo",
issues=issues,
dry_run=False,
checkpoint_file="checkpoint.json"
)
print(f"成功: {results.success_count}, 失败: {results.failure_count}")
if results.failures:
results.export_failures("failures.csv")
常见问题
Q1: GraphQL查询复杂度超限怎么办?
A: GitHub限制单次查询复杂度≤500000点。优化方案: (1)减少first参数值; (2)拆分为多次查询; (3)使用分页(cursor); (4)避免深层嵌套。专业版工具会自动计算复杂度并提示。
Q2: 批量操作中部分失败如何处理?
A: 专业版支持断点续传。失败项记录到failures.csv,可单独重试。检查失败原因(权限不足、资源不存在、限速等),修复后重试。
Q3: Webhook签名验证失败怎么办?
A: 检查: (1)secret是否与GitHub配置一致; (2)签名算法是否为HMAC-SHA256; (3)是否对原始请求体(非解析后JSON)计算签名; (4)比较时使用constant-time comparison。
Q4: Actions API触发工作流失败?
A: 常见原因: (1)工作流未配置workflow_dispatch触发器; (2)指定的ref不存在; (3)token缺少workflowscope; (4)inputs参数与工作流定义不匹配。
Q5: 如何监控API用量?
A: 通过响应头X-RateLimit-Remaining与X-RateLimit-Reset监控。专业版工具自动记录用量,运行gh-api-toolkit usage stats查看趋势。GraphQL与REST共享5000/小时配额。
Q6: 组织操作需要什么权限?
A: 组织级操作(管理成员、团队、仓库)需要admin:orgscope。团队管理还需对应团队的maintainer角色。建议使用组织级App而非个人token。
Q7: 如何导出搜索结果?
A: 搜索API返回total_count与items。使用分页参数page与per_page遍历。专业版支持--export csv/json直接导出全部结果。
Q8: 专业版支持GitHub App吗?
A: 支持。配置App ID、私钥、installation ID后,自动获取installation token。相比PAT,App token更安全(可细粒度授权、自动过期)。
Q9: 如何处理API版本兼容?
A: GitHub API通过Accept头指定版本(如application/vnd.github+json)。专业版工具会自动添加正确的Accept头。建议关注GitHub API变更日志,及时适配新版本。
Q10: 大规模数据同步如何优化?
A: (1)使用GraphQL减少请求次数; (2)启用增量同步(基于updated_at过滤); (3)并行请求(遵守限速); (4)本地缓存已同步数据; (5)使用Webhook实时同步变更。
错误处理
| 错误场景 | 原因 | 处理方式 |
|---|---|---|
| LLM响应超时或无响应 | 网络延迟或模型负载过高 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接,执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令请求;确认Agent平台LLM服务正常 |
| 输入内容格式不正确 | 用户输入不符合skill预期格式 | 检查输入是否符合skill使用说明中的格式要求,参考示例章节 |
| 执行结果与预期不符 | 指令描述不够明确或上下文不足 | 提供更详细的指令描述,补充必要的上下文信息 |
| 命令执行失败 | 运行环境不满足要求或权限不足 | 确认运行环境符合依赖说明中的要求;检查命令权限设置 |
已知限制
- 需要API Key,无Key环境无法使用
热门AI工具
相关专题
github中文官网入口https://docs.github.com/zh/get-started,GitHub 是一种基于云的平台,可在其中存储、共享并与他人一起编写代码。 通过将代码存储在GitHub 上的“存储库”中,你可以: “展示或共享”你的工作。 持续“跟踪和管理”对代码的更改。
7965
2026.01.21
要对比两个版本的 git 文件,请使用 git diff 命令:git diff 比较工作树和暂存区之间的差异。git diff 比较两个提交或标签之间的差异。git diff 输出显示差异块,其中 + 表示添加的行,- 表示删除的行, 表示修改的行。可使用 gitkraken、meld、beyond compare 等可视化工具更直观地查看差异。本专题为大家提供相关的文章、下载、课程内容,供大家免费下载体验。
2281
2024.04.09
git提交错误撤回的方法:git reset head^:撤回最后一次提交,恢复到提交前状态。git revert head:创建新提交,内容与之前提交相反。git reset :使用提交的 sha-1 哈希撤回指定提交。交互式舞台区:标记要撤回的特定更改,然后提交,排除已撤回更改。本专题为大家提供相关的文章、下载、课程内容,供大家免费下载体验。
2517
2024.04.09
Git是一个强大的版本控制系统,它提供了很多功能帮助开发人员有效地管理和控制代码的变更,本专题为大家提供git 撤销提交的commit相关的各种文章内容,供大家免费下载体验。
714
2023.07.24
git和svn的区别:1、定义不同;2、模型类型不同;3、存储单元不同;4、是否拥有全局版本号;5、内容完整性不同;6、版本库不同;7、克隆目录速度不同;8、分支不同。php中文网为大家带来了git和svn的相关知识、以及相关文章等内容。
1260
2023.07.06
本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。
0
2026.11.17
本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。
0
2026.11.17
热门下载
相关下载
精品课程

