REST API 现在已版本化。 有关更多信息，请参阅“关于 API 版本控制”。

用于 Git 引用 REST API 端点

使用 REST API 与 GitHub 上 Git 数据库中的引用进行交互

关于 Git 引用

Git 引用 (git ref) 是一个包含 Git 提交 SHA-1 哈希的文件。在引用 Git 提交时，您可以使用 Git 引用（一个易于记忆的名称）而不是哈希。Git 引用可以重写为指向新的提交。分支是一个 Git 引用，它存储新的 Git 提交哈希。这些端点允许您读取和写入 GitHub 上 Git 数据库的引用。

列出匹配的引用

返回与提供的名称匹配的 Git 数据库中的引用数组。URL 中的 :ref 必须格式化为 heads/<branch name>（用于分支）和 tags/<tag name>（用于标签）。如果存储库中不存在 :ref，但现有引用以 :ref 开头，则会将其作为数组返回。

在不提供 :ref 的情况下使用此端点时，它将返回 Git 数据库中所有引用的数组，包括服务器上存在的注释和存储。将返回命名空间中的任何内容，而不仅仅是 heads 和 tags。

注意

您需要显式请求拉取请求 以触发测试合并提交，该提交检查拉取请求的可合并性。有关更多信息，请参阅“检查拉取请求的可合并性”。

如果您请求名为 feature 的分支的匹配引用，但分支 feature 不存在，则响应仍可能包含以单词 feature 开头的其他匹配头引用，例如 featureA 和 featureB。

“列出匹配的引用”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “内容”存储库权限（读取）

如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。

“列出匹配的引用”的参数

标头
accept 字符串

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必需

存储库的帐户所有者。名称不区分大小写。

repo 字符串 必需

存储库的名称，不含 .git 扩展名。名称不区分大小写。

ref 字符串 必需

Git 引用。有关更多信息，请参阅 Git 文档中的Git 引用。

“列出匹配的引用”的 HTTP 响应状态代码

状态代码描述
200

确定

409

冲突

“列出匹配的引用”的代码示例

请求示例

获取/repos/{owner}/{repo}/git/matching-refs/{ref}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/git/matching-refs/REF

响应

状态：200
[ { "ref": "refs/heads/feature-a", "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWE=", "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-a", "object": { "type": "commit", "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd" } }, { "ref": "refs/heads/feature-b", "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWI=", "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-b", "object": { "type": "commit", "sha": "612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac" } } ]

获取引用

从 Git 数据库返回单个引用。URL 中的 :ref 必须格式化为 heads/<branch name>（用于分支）和 tags/<tag name>（用于标签）。如果 :ref 与现有引用不匹配，则返回 404。

注意

您需要显式请求拉取请求 以触发测试合并提交，该提交检查拉取请求的可合并性。有关更多信息，请参阅“检查拉取请求的可合并性”。

“获取引用”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “内容”存储库权限（读取）

如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。

“获取引用”的参数

标头
accept 字符串

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必需

存储库的帐户所有者。名称不区分大小写。

repo 字符串 必需

存储库的名称，不含 .git 扩展名。名称不区分大小写。

ref 字符串 必需

Git 引用。有关更多信息，请参阅 Git 文档中的Git 引用。

“获取引用”的 HTTP 响应状态代码

状态代码描述
200

确定

404

资源未找到

409

冲突

“获取引用”的代码示例

请求示例

获取/repos/{owner}/{repo}/git/ref/{ref}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/git/ref/REF

响应

状态：200
{ "ref": "refs/heads/featureA", "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==", "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA", "object": { "type": "commit", "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd" } }

创建引用

为您的存储库创建引用。即使使用的提交 SHA-1 哈希存在，您也无法为空存储库创建新引用。空存储库是没有分支的存储库。

“创建引用”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须至少具有以下权限集之一

  • “内容”存储库权限（写入）
  • “内容”存储库权限（写入） 和 “工作流”存储库权限（写入）

“创建引用”的参数

标头
accept 字符串

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必需

存储库的帐户所有者。名称不区分大小写。

repo 字符串 必需

存储库的名称，不含 .git 扩展名。名称不区分大小写。

主体参数
ref 字符串 必需

完全限定引用的名称（即：refs/heads/master）。如果它不以“refs”开头且至少有两个斜杠，则将被拒绝。

sha 字符串 必需

此引用的 SHA1 值。

“创建引用”的 HTTP 响应状态代码

状态代码描述
201

已创建

409

冲突

422

验证失败或端点已被滥用。

“创建引用”的代码示例

请求示例

发布/repos/{owner}/{repo}/git/refs
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/git/refs \ -d '{"ref":"refs/heads/featureA","sha":"aa218f56b14c9653891f9e74264a383fa43fefbd"}'

响应

状态：201
{ "ref": "refs/heads/featureA", "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==", "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA", "object": { "type": "commit", "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd" } }

更新引用

更新提供的引用以指向新的 SHA。有关更多信息，请参阅 Git 文档中的Git 引用。

“更新引用”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须至少具有以下权限集之一

  • “内容”存储库权限（写入）
  • “内容”存储库权限（写入） 和 “工作流”存储库权限（写入）

“更新引用”的参数

标头
accept 字符串

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必需

存储库的帐户所有者。名称不区分大小写。

repo 字符串 必需

存储库的名称，不含 .git 扩展名。名称不区分大小写。

ref 字符串 必需

Git 引用。有关更多信息，请参阅 Git 文档中的Git 引用。

主体参数
sha 字符串 必需

要将此引用设置为的 SHA1 值

force 布尔值

指示是否强制更新或确保更新是快进更新。省略此项或将其设置为 false 将确保您不会覆盖工作。

默认： false

“更新引用”的 HTTP 响应状态代码

状态代码描述
200

确定

409

冲突

422

验证失败或端点已被滥用。

“更新引用”的代码示例

请求示例

修补/repos/{owner}/{repo}/git/refs/{ref}
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/git/refs/REF \ -d '{"sha":"aa218f56b14c9653891f9e74264a383fa43fefbd","force":true}'

响应

状态：200
{ "ref": "refs/heads/featureA", "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==", "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA", "object": { "type": "commit", "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd" } }

删除引用

删除提供的引用。

“删除引用”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “内容”存储库权限（写入）

“删除引用”的参数

标头
accept 字符串

建议设置为 application/vnd.github+json。

路径参数
owner 字符串 必需

存储库的帐户所有者。名称不区分大小写。

repo 字符串 必需

存储库的名称，不含 .git 扩展名。名称不区分大小写。

ref 字符串 必需

Git 引用。有关更多信息，请参阅 Git 文档中的Git 引用。

“删除引用”的 HTTP 响应状态代码

状态代码描述
204

无内容

409

冲突

422

验证失败或端点已被滥用。

“删除引用”的代码示例

请求示例

删除/repos/{owner}/{repo}/git/refs/{ref}
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/git/refs/REF

响应

状态：204