GitHub搜索API总结 - 闻桂の小记

一、概述

GitHub是一个宝贵的情报、信息来源。通过GitHub搜索API，我们可以自动化地从GitHub上收集目标企业的邮箱、敏感信息、代码配置等数据，用于企业邮箱暴露面检测和安全审计。以下内容从官方文档抽离做了总结。

1.1 API类型与用途

API类型	接口	用途
代码搜索	`GET /search/code`	搜索文件内容中的代码
仓库搜索	`GET /search/repositories`	搜索符合特定条件的仓库
提交搜索	`GET /search/commits`	搜索提交记录和开发者信息
用户搜索	`GET /search/users`	搜索GitHub用户
议题搜索	`GET /search/issues`	搜索Issue和Pull Request

1.2 通用参数说明

所有搜索API共享以下通用参数：

参数名	类型	必需	说明
`q`	string	是	搜索查询字符串，包含关键词和限定符
`per_page`	integer	否	每页结果数，最大100，默认30
`page`	integer	否	页码，默认1
`sort`	string	否	排序方式，根据API类型不同而不同
`order`	string	否	排序顺序，desc（降序）或asc（升序），默认desc

二、接口说明

2.1 认证要求

API类型	认证要求	速率限制
代码搜索	必须认证	9-10 req/min
仓库搜索	推荐认证	30 req/min
其他搜索API	可选认证	30 req/min

Token类型：支持Personal Access Token和GitHub App Token，不需要任何特殊权限。

请求头格式：

Authorization: Bearer YOUR_TOKEN
Accept: application/vnd.github+json
X-GitHub-Api-Version: 2026-03-10

2.2 text-match元数据

text-match是GitHub搜索API提供的特殊功能，可以在搜索响应中直接返回匹配词的位置信息。

启用方式：在请求头中设置Accept为application/vnd.github.text-match+json

适用API：Search Code、Search Commits、Search Issues

响应字段：

字段	说明
`object_url`	包含匹配内容的资源URL
`fragment`	匹配词所在的文本片段（通常为200-300字符）
`matches`	匹配详情，包含匹配文本和位置索引

使用优势：减少API调用、无需单独下载文件即可获取匹配片段。

2.3 通用限制

限制类型	上限
查询长度	≤256字符（不含操作符和限定符）
AND/OR/NOT操作符数量	≤5个
每页最大结果数	100条
总结果数上限	1,000条（10页）

2.4 代码搜索特殊限制

必须包含搜索词：仅使用限定符（如language:python）是无效的
仅搜索默认分支：通常是main或master分支
文件大小限制：仅搜索小于384KB的文件
归档仓库限制：不搜索归档的仓库
仓库数量限制：最多搜索4,000个匹配的仓库

2.5 搜索关键词语法

GitHub搜索支持多种语法来构建复杂的查询条件。

布尔运算符

运算符	说明	示例
`AND`	同时满足两个条件	`cats AND dogs`
`OR`	满足任一条件	`cats OR dogs`
`NOT`	排除匹配结果	`cats NOT dogs`

示例：

@company.com AND NOT path:test

搜索包含@company.com但不在test目录中的结果。

数值比较

使用 >, >=, <, <= 进行数值比较：

运算符	说明	示例
`>`	大于	`stars:>1000`
`>=`	大于等于	`stars:>=1000`
`<`	小于	`size:<10000`
`<=`	小于等于	`stars:<=50`

示例：

example language:python stars:>100 forks:>50

搜索Python项目中包含example、Star大于100、Fork大于50的仓库。

范围查询

使用 n..n 语法搜索数值或日期范围：

语法	说明	示例
`n..n`	闭区间	`stars:10..50`
`n..*`	大于等于	`stars:10..*` 等同于 `stars:>=10`
`*..n`	小于等于	`stars:*..10` 等同于 `stars:<=10`

示例：

config pushed:2024-01-01..2024-12-31

搜索2024年内推送的包含config的仓库。

日期查询

日期格式必须遵循ISO8601标准：YYYY-MM-DD

语法	说明	示例
`>YYYY-MM-DD`	晚于日期	`created:>2024-01-01`
`>=YYYY-MM-DD`	不早于日期	`pushed:>=2024-06-01`
`<YYYY-MM-DD`	早于日期	`created:<2023-01-01`
`<=YYYY-MM-DD`	不晚于日期	`updated:<=2024-12-31`
`YYYY-MM-DD..YYYY-MM-DD`	日期区间	`created:2024-01-01..2024-06-30`

带时间的日期（可选）：

created:2017-01-01T01:00:00+08:00..2017-03-01T15:30:00+08:00

排除语法

使用 - 前缀排除特定限定符的结果：

语法	说明	示例
`-qualifier:value`	排除匹配qualifier的结果	`-language:javascript`

示例：

cats stars:>10 -language:javascript

搜索包含cats、Star大于10但不是JavaScript语言的仓库。

引号与空白字符

包含空格的查询需要使用引号包围：

场景	语法	示例
包含空格的词组	`"词组"`	`"hello world"`
带空格的标签	`label:"标签名"`	`label:"bug fix"`
带空格的用户名	`user:"用户名"`	`user:"john doe"`

示例：

build label:"bug fix" assignee:"john doe"

特殊用户查询

语法	说明	示例
`@me`	当前认证用户	`assignee:@me`
`@octocat`	指定GitHub用户名	`author:@octocat`

示例：

is:issue assignee:@me

搜索当前用户分配的Issue。

查询组合示例

邮箱收集查询：

@company.com in:file language:python NOT path:test NOT path:examples

敏感信息搜索：

password in:file extension:config OR extension:json OR extension:yaml

企业仓库发现：

example in:name OR example in:description org:companyname stars:>10

三、接口详情

3.1 代码搜索API（Search Code）

接口：GET https://api.github.com/search/code

说明：此接口要求必须进行身份认证，限制为每分钟最多10个请求。

请求Header参数：

参数名	类型	说明
`Accept`	string	推荐设置为 `application/vnd.github.text-match+json` 获取文本匹配元数据
`Authorization`	string	Bearer令牌，格式：`Bearer YOUR_TOKEN`
`X-GitHub-Api-Version`	string	API版本，推荐：`2026-03-10`

Query参数：

参数名	类型	必需	说明
`q`	string	是	搜索查询，包含关键词和限定符。必须至少包含一个搜索词。
`sort`	string	否	排序方式，即将废弃。仅支持 `indexed`。
`order`	string	否	排序顺序，默认 `desc`。可选值：`desc`或`asc`。
`per_page`	integer	否	每页结果数，最大100，默认30。
`page`	integer	否	页码，默认1。

请求示例：

GET https://api.github.com/search/code?q=@example.com+in:file&per_page=100&page=1
Accept: application/vnd.github.text-match+json
Authorization: Bearer ghp_xxxxxxxxxxxx
X-GitHub-Api-Version: 2026-03-10

响应结构：

{
  "total_count": 7,
  "incomplete_results": false,
  "items": [
    {
      "name": "classes.js",
      "path": "src/attributes/classes.js",
      "sha": "d7212f9dee2dcc18f084d7df8f417b80846ded5a",
      "url": "https://api.github.com/repositories/167174/contents/src/attributes/classes.js",
      "repository": {
        "id": 167174,
        "name": "jquery",
        "full_name": "jquery/jquery",
        "owner": { "login": "jquery", "type": "Organization" },
        "private": false,
        "description": "jQuery JavaScript Library"
      },
      "score": 1
    }
  ],
  "text_matches": [
    {
      "object_url": "https://api.github.com/repos/owner/repo/contents/config.json",
      "fragment": "...contact@example.com admin@example.com...",
      "matches": [
        { "text": "example.com", "indices": [[14, 26], [32, 44]] }
      ]
    }
  ]
}

响应字段说明：

字段	类型	说明
`total_count`	integer	搜索结果总数
`incomplete_results`	boolean	是否为不完整结果（查询超时时为true）
`items`	array	结果数组，包含所有匹配的代码文件
`items[].name`	string	文件名
`items[].path`	string	文件路径
`items[].url`	string	API下载链接
`items[].repository`	object	仓库信息对象
`items[].score`	number	相关度评分
`text_matches`	array	文本匹配元数据

搜索限定符：

限定符	说明	示例
`in:file`	搜索文件内容	`@example.com in:file`
`in:path`	搜索文件路径	`config in:path`
`filename:NAME`	按文件名搜索	`filename:.gitconfig`
`extension:EXT`	按文件扩展名	`extension:json`
`language:LANG`	按编程语言	`language:python`
`path:PATH`	在指定目录搜索	`path:config`
`size:N`	按文件大小（字节）	`size:>1000`
`user:USERNAME`	搜索用户仓库	`user:octocat`
`org:ORGNAME`	搜索组织仓库	`org:microsoft`
`repo:USER/REPO`	搜索特定仓库	`repo:jquery/jquery`
`fork:true`	包含fork仓库	`fork:true`
`NOT`	排除结果	`NOT path:test`

HTTP状态码：

状态码	说明
`200`	OK - 请求成功
`304`	Not Modified - 资源未修改
`403`	Forbidden - 禁止访问（速率限制）
`422`	Unprocessable Entity - 查询无效
`503`	Service Unavailable - 服务不可用

3.2 仓库搜索API（Search Repositories）

接口：GET https://api.github.com/search/repositories

说明：用于搜索符合特定条件的仓库，适用于发现目标企业的开源项目。

请求Header参数：与代码搜索API相同。

Query参数：

参数名	类型	必需	说明
`q`	string	是	搜索查询，包含关键词和限定符
`sort`	string	否	排序方式：`stars`、`forks`、`help-wanted-issues`、`updated`。默认最佳匹配
`order`	string	否	排序顺序，默认 `desc`。可选值：`desc`或`asc`
`per_page`	integer	否	每页结果数，最大100，默认30
`page`	integer	否	页码，默认1

请求示例：

GET https://api.github.com/search/repositories?q=example+in:name&sort=stars&order=desc&per_page=100
Accept: application/vnd.github+json
Authorization: Bearer ghp_xxxxxxxxxxxx
X-GitHub-Api-Version: 2026-03-10

响应结构：

{
  "total_count": 1000,
  "incomplete_results": false,
  "items": [
    {
      "id": 167174,
      "name": "jquery",
      "full_name": "jquery/jquery",
      "owner": { "login": "jquery", "type": "Organization" },
      "private": false,
      "description": "jQuery JavaScript Library",
      "url": "https://api.github.com/repos/jquery/jquery",
      "created_at": "2010-03-08T09:41:56Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "stargazers_count": 58000,
      "forks_count": 20000,
      "language": "JavaScript",
      "topics": ["javascript", "jquery", "library", "web"],
      "score": 100.0
    }
  ]
}

响应字段说明：

字段	类型	说明
`total_count`	integer	搜索结果总数
`items`	array	结果数组
`items[].id`	integer	仓库唯一标识符
`items[].name`	string	仓库名称
`items[].full_name`	string	完整仓库名（owner/name）
`items[].owner`	object	仓库所有者信息
`items[].private`	boolean	是否为私有仓库
`items[].description`	string	仓库描述
`items[].stargazers_count`	integer	Star数量
`items[].forks_count`	integer	Fork数量
`items[].language`	string	主要编程语言
`items[].topics`	array	仓库主题/标签
`items[].score`	number	相关度评分

搜索限定符：

限定符	说明	示例
`in:name`	搜索仓库名称	`jquery in:name`
`in:description`	搜索仓库描述	`example in:description`
`in:readme`	搜索README文件	`tutorial in:readme`
`user:USERNAME`	搜索用户仓库	`user:octocat`
`org:ORGNAME`	搜索组织仓库	`org:microsoft`
`language:LANG`	按语言筛选	`language:JavaScript`
`stars:>=N`	按Star数量筛选	`stars:>=1000`
`forks:>=N`	按Fork数量筛选	`forks:>=500`
`pushed:>DATE`	按最后推送时间筛选	`pushed:>2024-01-01`
`topic:TOPIC`	按主题筛选	`topic:security`
`is:public`	仅公开仓库	`is:public`
`is:archived`	仅归档仓库	`is:archived`

HTTP状态码：

状态码	说明
`200`	OK - 请求成功
`304`	Not Modified - 资源未修改
`422`	Unprocessable Entity - 查询无效

3.3 Commits搜索API（Search Commits）

接口：GET https://api.github.com/search/commits

说明：用于搜索Git提交记录，可获取提交中的作者和提交者邮箱。

与前两节的差异：

差异项	说明
认证要求	可选，推荐认证（30 req/min）
速率限制	30 req/min（未认证10 req/min）
支持text-match	是
sort参数	支持：`author-date`、`committer-date`

响应结构特点：

字段	说明
`items[].sha`	提交SHA值
`items[].commit`	提交信息对象
`items[].commit.author.email`	作者邮箱 ⭐
`items[].commit.committer.email`	提交者邮箱 ⭐
`items[].author`	GitHub用户对象（作者）

搜索限定符：

限定符	说明	示例
`author:NAME`	按作者名搜索	`author:octocat`
`author-email:EMAIL`	按作者邮箱搜索	`author-email:@example.com`
`committer:NAME`	按提交者搜索	`committer:octocat`
`repo:OWNER/REPO`	搜索特定仓库	`repo:jquery/jquery`
`hash:HASH`	按提交SHA搜索	`hash:abc123`

3.4 Users搜索API（Search Users）

接口：GET https://api.github.com/search/users

说明：用于搜索GitHub用户。

与前两节的差异：

差异项	说明
认证要求	可选，推荐认证（30 req/min）
速率限制	30 req/min（未认证10 req/min）
支持text-match	❌ 否
sort参数	支持：`followers`、`repositories`、`joined`
响应结构	不同于前两者，包含用户基本信息

响应结构特点：

字段	说明
`items[].login`	用户登录名
`items[].avatar_url`	头像图片URL
`items[].html_url`	Web页面URL
`items[].type`	用户类型（User或Bot）
`items[].site_admin`	是否为GitHub站点管理员
`items[].followers_url`	粉丝列表API URL

搜索限定符：

限定符	说明	示例
`in:login`	搜索登录名	`octocat in:login`
`in:email`	搜索邮箱	`john@example.com in:email`
`in:fullname`	搜索全名	`John Doe in:fullname`
`type:user`	仅用户	`type:user`
`followers:>=N`	按粉丝数量筛选	`followers:>=100`
`location:LOCATION`	按地区筛选	`location:Beijing`

3.5 Issues搜索API（Search Issues）

接口：GET https://api.github.com/search/issues

说明：同时搜索Issue和Pull Request。

与前两节的差异：

差异项	说明
认证要求	可选，推荐认证（30 req/min）
速率限制	30 req/min（未认证10 req/min）
支持text-match	是
sort参数	支持：`comments`、`reactions`、`created`、`updated`

响应结构特点：

字段	说明
`items[].number`	Issue/PR编号
`items[].state`	状态：open（开放）、closed（关闭）
`items[].title`	标题
`items[].body`	正文内容
`items[].user`	创建者用户对象
`items[].labels`	标签数组
`items[].comments`	评论数量
`items[].pull_request`	PR特有字段（Issue无此字段）

搜索限定符：

限定符	说明	示例
`in:title`	搜索标题	`bug in:title`
`in:body`	搜索正文	`error in:body`
`in:comments`	搜索评论	`question in:comments`
`is:issue`	仅Issue	`is:issue`
`is:pr`	仅Pull Request	`is:pr`
`is:open`	仅开放状态	`is:open`
`author:USERNAME`	按创建者筛选	`author:octocat`
`label:LABEL`	按标签筛选	`label:bug`

参考资料：

2026 年 4 月
日	一	二	三	四	五	六
			1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30