Git 参考的 REST API 端点

关于 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.

fine_grained_access

works_with_fine_grained_tokens:

permission_set:

"Contents" repository permissions (read)

allows_public_read_access

“”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 Git reference. For more information, see "Git References" in the Git documentation.

http_status_code

status_code	说明
`200`	OK
`409`	Conflict

code_samples

request_example

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: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/git/matching-refs/REF

Response

Status: 200

[
  {
    "ref": "refs/heads/feature-a",
    "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWE=",
    "url": "https://HOSTNAME/repos/octocat/Hello-World/git/refs/heads/feature-a",
    "object": {
      "type": "commit",
      "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
      "url": "https://HOSTNAME/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
    }
  },
  {
    "ref": "refs/heads/feature-b",
    "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWI=",
    "url": "https://HOSTNAME/repos/octocat/Hello-World/git/refs/heads/feature-b",
    "object": {
      "type": "commit",
      "sha": "612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac",
      "url": "https://HOSTNAME/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".

fine_grained_access

works_with_fine_grained_tokens:

permission_set:

"Contents" repository permissions (read)

allows_public_read_access

“”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 Git reference. For more information, see "Git References" in the Git documentation.

http_status_code

status_code	说明
`200`	OK
`404`	Resource not found
`409`	Conflict

code_samples

request_example

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: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/git/ref/REF

Response

Status: 200

{
  "ref": "refs/heads/featureA",
  "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
  "url": "https://HOSTNAME/repos/octocat/Hello-World/git/refs/heads/featureA",
  "object": {
    "type": "commit",
    "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
    "url": "https://HOSTNAME/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.

fine_grained_access

works_with_fine_grained_tokens:

permission_sets:

"Contents" repository permissions (write)
"Contents" repository permissions (write) and "Workflows" repository permissions (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.

http_status_code

status_code	说明
`201`	Created
`409`	Conflict
`422`	Validation failed, or the endpoint has been spammed.

code_samples

request_example

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: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/git/refs \
  -d '{"ref":"refs/heads/featureA","sha":"aa218f56b14c9653891f9e74264a383fa43fefbd"}'

Response

Status: 201

{
  "ref": "refs/heads/featureA",
  "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
  "url": "https://HOSTNAME/repos/octocat/Hello-World/git/refs/heads/featureA",
  "object": {
    "type": "commit",
    "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
    "url": "https://HOSTNAME/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
  }
}

Update a reference

Updates the provided reference to point to a new SHA. For more information, see "Git References" in the Git documentation.

fine_grained_access

works_with_fine_grained_tokens:

permission_sets:

"Contents" repository permissions (write)
"Contents" repository permissions (write) and "Workflows" repository permissions (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 Git reference. 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`

http_status_code

status_code	说明
`200`	OK
`409`	Conflict
`422`	Validation failed, or the endpoint has been spammed.

code_samples

request_example

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: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/git/refs/REF \
  -d '{"sha":"aa218f56b14c9653891f9e74264a383fa43fefbd","force":true}'

Response

Status: 200

{
  "ref": "refs/heads/featureA",
  "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
  "url": "https://HOSTNAME/repos/octocat/Hello-World/git/refs/heads/featureA",
  "object": {
    "type": "commit",
    "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
    "url": "https://HOSTNAME/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
  }
}

Delete a reference

Deletes the provided reference.

fine_grained_access

works_with_fine_grained_tokens:

permission_set:

"Contents" repository permissions (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 Git reference. For more information, see "Git References" in the Git documentation.

http_status_code

status_code	说明
`204`	No Content
`409`	Conflict
`422`	Validation failed, an attempt was made to delete the default branch, or the endpoint has been spammed.

code_samples

request_example

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: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/git/refs/REF

Response

Status: 204