用于 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/<分支名称>（分支）和 tags/<标签名称>（标签）。如果 :ref 不存在于存储库中，但现有引用以 :ref 开头，则它们将作为数组返回。
当您在不提供 :ref 的情况下使用此端点时，它将返回 Git 数据库中的所有引用数组，包括注释和隐藏（如果它们存在于服务器上）。命名空间中的任何内容都会被返回，而不仅仅是 heads 和 tags。
注意：您需要显式地 请求拉取请求 以触发测试合并提交，该提交会检查拉取请求的可合并性。有关更多信息，请参阅“检查拉取请求的可合并性”。
如果您请求与名为 feature 的分支匹配的引用，但 feature 分支不存在，则响应仍然可以包含以 feature 开头的其他匹配的头部引用，例如 featureA 和 featureB。
“列出匹配的引用”的细粒度访问令牌
此端点适用于以下细粒度令牌类型
细粒度令牌必须具有以下权限集
- “内容”存储库权限（读取）
如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。
“列出匹配的引用”的参数
| 名称、类型、描述 |
|---|
accept string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需存储库的帐户所有者。名称不区分大小写。 |
repo string 必需存储库的名称，不包含 |
ref string 必需Git 引用。有关更多信息，请参阅 Git 文档中的“Git 引用”。 |
“列出匹配的引用”的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | OK |
409 | 冲突 |
“列出匹配的引用”的代码示例
请求示例
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 string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需存储库的帐户所有者。名称不区分大小写。 |
repo string 必需存储库的名称，不包含 |
ref string 必需Git 引用。有关更多信息，请参阅 Git 文档中的“Git 引用”。 |
用于“获取引用”的 HTTP 响应状态码
| 状态代码 | 描述 |
|---|---|
200 | OK |
404 | 资源未找到 |
409 | 冲突 |
用于“获取引用”的代码示例
请求示例
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 string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需存储库的帐户所有者。名称不区分大小写。 |
repo string 必需存储库的名称，不包含 |
| 名称、类型、描述 |
|---|
ref string 必需完全限定引用的名称（例如： |
sha 字符串 必需此引用的 SHA1 值。 |
创建引用时的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
201 | 已创建 |
409 | 冲突 |
422 | 验证失败或端点已被垃圾邮件攻击。 |
创建引用时的代码示例
请求示例
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 References”。
更新引用时的细粒度访问令牌
此端点适用于以下细粒度令牌类型
细粒度令牌必须至少具有以下权限集之一
- "内容" 仓库权限（写入）
- "内容" 仓库权限（写入） 和 "工作流" 仓库权限（写入）
更新引用时的参数
| 名称、类型、描述 |
|---|
accept string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需存储库的帐户所有者。名称不区分大小写。 |
repo string 必需存储库的名称，不包含 |
ref string 必需Git 引用。有关更多信息，请参阅 Git 文档中的“Git 引用”。 |
| 名称、类型、描述 |
|---|
sha 字符串 必需要将此引用设置为的 SHA1 值 |
force 布尔值 指示是否强制更新或确保更新是快进更新。省略此选项或将其设置为 默认: |
更新引用时的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | OK |
409 | 冲突 |
422 | 验证失败或端点已被垃圾邮件攻击。 |
更新引用时的代码示例
请求示例
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 string 建议设置为 |
| 名称、类型、描述 |
|---|
owner string 必需存储库的帐户所有者。名称不区分大小写。 |
repo string 必需存储库的名称，不包含 |
ref string 必需Git 引用。有关更多信息，请参阅 Git 文档中的“Git 引用”。 |
删除引用时的 HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
204 | 无内容 |
409 | 冲突 |
422 | 验证失败或端点已被垃圾邮件攻击。 |
删除引用时的代码示例
请求示例
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