Skip to main content
REST API 现已经过版本控制。 有关详细信息,请参阅“关于 API 版本控制”。

Git 参考的 REST API 终结点

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

关于 Git 引用

Git 引用 (git ref) 是一个包含 Git 提交 SHA-1 哈希的文件。 当引用 Git 提交时,你可以使用 Git 引用,与哈希相比这是一个易于记住的名称。 可以重写 Git 引用指向新的提交。 分支是存储新 Git 提交哈希的 Git 引用。 通过这些终结点,可以在 GitHub 上读取引用并将其写入 Git 数据库。

List matching references

Returns an array of references from your Git database that match the supplied name. The :ref in the URL must be formatted as heads/<branch name> for branches and tags/<tag name> for tags. If the :ref doesn't exist in the repository, but existing refs start with :ref, they will be returned as an array.

When you use this endpoint without providing a :ref, it will return an array of all the references from your Git database, including notes and stashes if they exist on the server. Anything in the namespace is returned, not just heads and tags.

Note: You need to explicitly request a pull request to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see "Checking mergeability of pull requests".

If you request matching references for a branch named feature but the branch feature doesn't exist, the response can still include other matching head refs that start with the word feature, such as featureA and featureB.

“List matching references”的细粒度访问令牌

此终结点适用于以下令牌类型:

令牌必须具有以下权限集:

  • contents:read

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

“List matching references”的参数

标头
名称, 类型, 说明
accept string

Setting to application/vnd.github+json is recommended.

路径参数
名称, 类型, 说明
owner string 必须

The account owner of the repository. The name is not case sensitive.

repo string 必须

The name of the repository without the .git extension. The name is not case sensitive.

ref string 必须

The commit reference. Can be a commit SHA, branch name (heads/BRANCH_NAME), or tag name (tags/TAG_NAME). For more information, see "Git References" in the Git documentation.

“List matching references”的 HTTP 响应状态代码

状态代码说明
200

OK

“List matching references”的示例代码

请求示例

get/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

Response

Status: 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" } } ]

Get a reference

Returns a single reference from your Git database. The :ref in the URL must be formatted as heads/<branch name> for branches and tags/<tag name> for tags. If the :ref doesn't match an existing ref, a 404 is returned.

Note: You need to explicitly request a pull request to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see "Checking mergeability of pull requests".

“Get a reference”的细粒度访问令牌

此终结点适用于以下令牌类型:

令牌必须具有以下权限集:

  • contents:read

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

“Get a reference”的参数

标头
名称, 类型, 说明
accept string

Setting to application/vnd.github+json is recommended.

路径参数
名称, 类型, 说明
owner string 必须

The account owner of the repository. The name is not case sensitive.

repo string 必须

The name of the repository without the .git extension. The name is not case sensitive.

ref string 必须

The commit reference. Can be a commit SHA, branch name (heads/BRANCH_NAME), or tag name (tags/TAG_NAME). For more information, see "Git References" in the Git documentation.

“Get a reference”的 HTTP 响应状态代码

状态代码说明
200

OK

404

Resource not found

“Get a reference”的示例代码

请求示例

get/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

Response

Status: 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" } }

Create a reference

Creates a reference for your repository. You are unable to create new references for empty repositories, even if the commit SHA-1 hash used exists. Empty repositories are repositories without branches.

“Create a reference”的细粒度访问令牌

此终结点适用于以下令牌类型:

令牌必须至少具有以下权限集之一:

  • contents:write
  • contents:write and workflows:write

“Create a reference”的参数

标头
名称, 类型, 说明
accept string

Setting to application/vnd.github+json is recommended.

路径参数
名称, 类型, 说明
owner string 必须

The account owner of the repository. The name is not case sensitive.

repo string 必须

The name of the repository without the .git extension. The name is not case sensitive.

正文参数
名称, 类型, 说明
ref string 必须

The name of the fully qualified reference (ie: refs/heads/master). If it doesn't start with 'refs' and have at least two slashes, it will be rejected.

sha string 必须

The SHA1 value for this reference.

“Create a reference”的 HTTP 响应状态代码

状态代码说明
201

Created

422

Validation failed, or the endpoint has been spammed.

“Create a reference”的示例代码

请求示例

post/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"}'

Response

Status: 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" } }

Update a reference

“Update a reference”的细粒度访问令牌

此终结点适用于以下令牌类型:

令牌必须至少具有以下权限集之一:

  • contents:write
  • contents:write and workflows:write

“Update a reference”的参数

标头
名称, 类型, 说明
accept string

Setting to application/vnd.github+json is recommended.

路径参数
名称, 类型, 说明
owner string 必须

The account owner of the repository. The name is not case sensitive.

repo string 必须

The name of the repository without the .git extension. The name is not case sensitive.

ref string 必须

The name of the reference to update (for example, heads/featureA). Can be a branch name (heads/BRANCH_NAME) or tag name (tags/TAG_NAME). For more information, see "Git References" in the Git documentation.

正文参数
名称, 类型, 说明
sha string 必须

The SHA1 value to set this reference to

force boolean

Indicates whether to force the update or to make sure the update is a fast-forward update. Leaving this out or setting it to false will make sure you're not overwriting work.

默认: false

“Update a reference”的 HTTP 响应状态代码

状态代码说明
200

OK

422

Validation failed, or the endpoint has been spammed.

“Update a reference”的示例代码

请求示例

patch/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}'

Response

Status: 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" } }

Delete a reference

“Delete a reference”的细粒度访问令牌

此终结点适用于以下令牌类型:

令牌必须具有以下权限集:

  • contents:write

“Delete a reference”的参数

标头
名称, 类型, 说明
accept string

Setting to application/vnd.github+json is recommended.

路径参数
名称, 类型, 说明
owner string 必须

The account owner of the repository. The name is not case sensitive.

repo string 必须

The name of the repository without the .git extension. The name is not case sensitive.

ref string 必须

The commit reference. Can be a commit SHA, branch name (heads/BRANCH_NAME), or tag name (tags/TAG_NAME). For more information, see "Git References" in the Git documentation.

“Delete a reference”的 HTTP 响应状态代码

状态代码说明
204

No Content

422

Validation failed, or the endpoint has been spammed.

“Delete a reference”的示例代码

请求示例

delete/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

Response

Status: 204