GitHub API工具包(免费版)

通过GitHub REST API管理仓库、Issue、Pull Request与分支,封装常用端点,提供CLI与Python两种调用方式,适合个人开发者集成场景。

概述

GitHub REST API是管理GitHub资源的标准接口,但官方API文档庞大,新手难以快速找到所需端点。本Skill封装最常用的API端点,提供场景化调用示例,帮助开发者在命令行或脚本中快速完成GitHub操作,无需翻阅文档。

免费版聚焦基础CRUD能力,适合个人开发者日常集成。

核心能力

认证机制

所有API调用需要Personal Access Token(PAT)认证:

输入格式

参数名	类型	必填	说明
input	string	是	GitHub API工具包(免费版)处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

# 设置环境变量(推荐)
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
# ...
# 验证token有效性
curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.user

Token权限建议:

repo: 仓库完整访问(含私有)
read:org: 读取组织信息
workflow: 管理Actions工作流

输入: 用户提供认证机制所需的指令和必要参数。处理: 解析认证机制的输入参数,完成核心逻辑,返回结构化响应。输出: 返回认证机制的响应数据,包含状态码、结果和日志。

仓库管理

# 列出认证用户的仓库
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.user/repos?sort=updated&per_page=10"
# ...
# 查看指定仓库
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.repos/owner/repo"
# ...
# 创建新仓库
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-new-repo","description":"新仓库","private":true}' \
  "https://api.user/repos"
# ...
# 更新仓库设置
curl -X PATCH -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"更新描述","has_issues":true}' \
  "https://api.repos/owner/repo"

输入: 用户提供仓库管理所需的指令和必要参数。处理: 解析仓库管理的输入参数,完成核心逻辑,返回结构化响应。输出: 返回仓库管理的响应数据,包含状态码、结果和日志。

执行此能力时使用input_params参数,支持创建/查询/导出操作

Issue管理

# 列出仓库Issue
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.repos/owner/repo/issues?state=open&per_page=10"
# ...
# 查看指定Issue
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.repos/owner/repo/issues/123"
# ...
# 创建Issue
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"发现bug","body":"问题描述","labels":["bug"]}' \
  "https://api.repos/owner/repo/issues"
# ...
# 关闭Issue
curl -X PATCH -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state":"closed","state_reason":"completed"}' \
  "https://api.repos/owner/repo/issues/123"
# ...
# 添加评论
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"这是一条评论"}' \
  "https://api.repos/owner/repo/issues/123/comments"

输入: 用户提供Issue管理所需的指令和必要参数。处理: 解析Issue管理的输入参数,完成核心逻辑,返回结构化响应。输出: 返回Issue管理的响应数据,包含状态码、结果和日志。

执行此能力时使用input_params参数,支持创建/查询/导出操作

Pull Request管理

# 列出仓库PR
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.repos/owner/repo/pulls?state=open&per_page=10"
# ...
# 查看PR详情
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.repos/owner/repo/pulls/55"
# ...
# 创建PR
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"新功能","head":"feature-branch","base":"main","body":"变更说明"}' \
  "https://api.repos/owner/repo/pulls"
# ...
# 合并PR
curl -X PUT -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"commit_title":"合并PR","merge_method":"squash"}' \
  "https://api.repos/owner/repo/pulls/55/merge"

输入: 用户提供Pull Request管理所需的指令和必要参数。处理: 解析Pull Request管理的输入参数,完成核心逻辑,返回结构化响应。输出: 返回Pull Request管理的响应数据,包含状态码、结果和日志。

执行此能力时使用input_params参数,支持创建/查询/导出操作

分支与提交管理

# 列出分支
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.repos/owner/repo/branches?per_page=30"
# ...
# 查看提交历史
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.repos/owner/repo/commits?sha=main&per_page=10"
# ...
# 比较两个提交
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.repos/owner/repo/compare/main...feature-branch"

输入: 用户提供分支与提交管理所需的指令和必要参数。处理: 解析分支与提交管理的输入参数,完成核心逻辑,返回结构化响应。输出: 返回分支与提交管理的响应数据,包含状态码、结果和日志。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：REST、管理仓库、与分支、支持基础、CRUD、与结构化输出、适合个人开发者集、成场景、工具包、免费版、是一款面向开发者、集成工具、封装常用、帮助用户通过命令、行或脚本管理仓库、核心能力、CLI、Python、两种调用方式等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

执行此能力时使用input_params参数,支持创建/查询/导出操作

使用场景

场景1:CI/CD流水线中创建Release Issue

用户意图: "每次发布自动在仓库创建一个Release Issue,记录变更。"

#!/bin/bash
# 在CI流水线中调用
VERSION=$(git describe --tags)
CHANGELOG=$(cat CHANGELOG.md)
# ...
curl -X POST -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"Release $VERSION\",\"body\":\"$CHANGELOG\",\"labels\":[\"release\"]}" \
  "https://api.repos/$REPO/issues"

场景2:批量查看团队成员的PR

用户意图: "看看团队5个人本周提交了哪些PR。"

#!/bin/bash
members=("alice" "bob" "carol" "dave" "eve")
for member in "${members[@]}"; do
  echo "=== $member 的PR ==="
  curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
    "https://api.search/issues?q=author:$member+is:pr+created:>2026-07-11" \
    | jq '.items[] | {number, title, state: .state, repo: .repository_url}'
done

场景3:监控仓库的开放Issue数量

用户意图: "每天早上统计仓库的开放Issue数,超过50就告警。"

#!/bin/bash
COUNT=$(curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.repos/owner/repo/issues?state=open" \
  | jq 'length')
# ...
echo "当前开放Issue数: $COUNT"
if [ "$COUNT" -gt 50 ]; then
  echo "WARNING: Issue数量超过阈值"
  # 发送告警通知
fi

不适用场景

以下场景GitHub API工具包(免费版)不适合处理：

逆向工程闭源API
API安全渗透测试
非标准协议集成

触发条件

需要API集成、接口对接、Webhook配置、系统连接时使用。不适用于非本工具能力范围的需求。

快速开始

Step 1:获取Token

登录GitHub,进入Settings → Developer settings → Personal access tokens
生成新token,勾选所需scope(建议repo、read:org)
复制token,保存到安全位置

Step 2:配置环境

# 设置环境变量
export GITHUB_TOKEN="ghp_your_token_here"
# ...
# 验证认证
curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.user

Step 3:首次API调用

# 列出你的仓库
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.user/repos?per_page=5" | jq '.[].full_name'

Step 4:Python集成

import os
import requests
# ...
token = os.environ['GITHUB_TOKEN']
headers = {
    'Authorization': f'Bearer {token}',
    'Accept': 'application/vnd.github+json'
}
# ...
# 列出仓库
response = requests.get(
    'https://api.user/repos',
    headers=headers,
    params={'sort': 'updated', 'per_page': 10}
)
repos = response.json()
for repo in repos:
    print(f"{repo['full_name']}: {repo['description']}")

示例

通用请求模板

# 通用GET请求
gh-api-get() {
  local endpoint=$1
  curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
       -H "Accept: application/vnd.github+json" \
       "https://api.github.com$endpoint"
}
# ...
# 通用POST请求
gh-api-post() {
  local endpoint=$1
  local data=$2
  curl -s -X POST -H "Authorization: Bearer $GITHUB_TOKEN" \
       -H "Accept: application/vnd.github+json" \
       -H "Content-Type: application/json" \
       -d "$data" \
       "https://api.github.com$endpoint"
}
# ...
# 使用示例
gh-api-get "/repos/owner/repo/issues?state=open" | jq '.[].title'
gh-api-post "/repos/owner/repo/issues" '{"title":"测试","body":"内容"}'

Python封装类

import os
import requests
# ...
class GitHubAPI:
    def __init__(self, token=None):
        self.token = token or os.environ['GITHUB_TOKEN']
        self.headers = {
            'Authorization': f'Bearer {self.token}',
            'Accept': 'application/vnd.github+json'
        }
        self.base_url = 'https://api.github.com'
# ...
    def list_repos(self, sort='updated', per_page=30):
        resp = requests.get(
            f'{self.base_url}/user/repos',
            headers=self.headers,
            params={'sort': sort, 'per_page': per_page}
        )
        resp.raise_for_status()
        return resp.json()
# ...
    def list_issues(self, owner, repo, state='open'):
        resp = requests.get(
            f'{self.base_url}/repos/{owner}/{repo}/issues',
            headers=self.headers,
            params={'state': state}
        )
        resp.raise_for_status()
        return resp.json()
# ...
    def create_issue(self, owner, repo, title, body='', labels=None):
        data = {'title': title, 'body': body}
        if labels:
            data['labels'] = labels
        resp = requests.post(
            f'{self.base_url}/repos/{owner}/{repo}/issues',
            headers=self.headers,
            json=data
        )
        resp.raise_for_status()
        return resp.json()

最佳实践

API调用规范

规范	说明	示例
使用Bearer认证	新版API推荐Bearer	`Authorization: Bearer $TOKEN`
设置Accept头	指定API版本	`Accept: application/vnd.github+json`
限制per_page	避免响应过大	`per_page=30`(最大100)
处理分页	使用Link header	解析`rel="next"`获取下一页
错误处理	检查状态码	4xx/5xx时记录并重试

已知限制

GitHub API对认证用户的限制为5000请求/小时,搜索API为30次/分钟:

# 查看当前速率限制
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.rate_limit | jq '.rate'
# ...
# 响应头包含限制信息
# X-RateLimit-Limit: 5000
# X-RateLimit-Remaining: 4999
# X-RateLimit-Reset: 1620000000

安全要点

Token存储: 通过环境变量传递,禁止硬编码
权限最小化: 仅勾选所需scope,避免admin:*
Token轮换: 每90天更换一次
日志脱敏: 日志中不记录Authorization头
HTTPS强制: 所有请求走HTTPS,禁止HTTP降级
当前为免费版本,如需完整功能请升级到付费版获取全部能力

常见问题

Q1: API返回401 Unauthorized怎么办?

A: 检查: (1)token是否正确设置(echo $GITHUB_TOKEN); (2)token是否过期; (3)Authorization头格式是否正确(Bearer <token>); (4)token是否有所需scope。

Q2: API返回403 Forbidden怎么办?

A: 可能原因: (1)权限不足,token缺少对应scope; (2)触发速率限制(检查X-RateLimit-Remaining); (3)操作的是组织仓库但token无read:org权限; (4)仓库设置为限制操作。

Q3: 如何处理分页?

A: GitHub使用page-based分页。通过page和per_page参数控制。响应头Link中包含rel="next"和rel="last"链接。循环请求直到next不存在。

Q4: 创建/更新文件时content字段怎么处理?

A: 文件内容必须Base64编码后传入content字段。更新文件还需提供文件的sha(通过GET获取)。示例: echo -n "content" | base64。

Q5: 搜索API和普通API有什么区别?

A: 搜索API(/search/...)有独立的速率限制(30次/分钟),且查询语法不同(支持q=keyword+label:bug+state:open)。结果结构也不同(包含total_count和items)。搜索查询可能超时,建议缩小范围。

免费版限制

本免费体验版限制以下高级功能:

不支持GraphQL API(仅REST)
不支持批量操作(单次仅处理1个资源)
不支持高级搜索(复杂查询语法)
不支持Webhook管理
不支持GitHub Actions API
不支持组织与团队管理API

解锁全部功能请使用专业版: github-api-toolkit-pro

依赖说明

运行环境

Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
操作系统: Windows / macOS / Linux
网络: 可访问GitHub API(api.github.com)
Python: 3.8+(可选,用于Python集成)

依赖详情

依赖项	类型	是否必需	获取方式
curl	命令行工具	必需	系统自带
jq	命令行工具	可选	`brew install jq`
requests	Python库	可选	`pip install requests`
GitHub账号	在线服务	必需	注册GitHub账号并生成PAT
LLM API	API	必需	由Agent平台内置LLM提供

API Key 配置

GitHub Token: 通过环境变量GITHUB_TOKEN配置,禁止硬编码
Token存储: 建议使用密码管理器或.env文件(已gitignore)
Token权限: 根据需要选择scope,遵循最小权限原则
Token轮换: 每90天更换,使用gh api user验证新token
禁止: 在SKILL.md或脚本中硬编码任何Token

可用性分类

分类: MD+EXEC+API(Markdown指令+命令行工具+REST API调用)
说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent完成操作,核心功能通过curl或Python调用GitHub REST API

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

输出格式

{
  "success": true,
  "data": {
    "result": "GitHub API工具包(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "github apikit"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}

Github Api Toolkit Free

安装到 Tokeny（自动）

SKILL.md