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" repository permissions (read)

공용 리소스만 요청되는 경우 인증 또는 앞서 언급한 권한 없이 이 엔드포인트를 사용할 수 있습니다.

"List matching references"에 대한 매개 변수

머리글
속성, 형식, 설명
accept string

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

경로 매개 변수
속성, 형식, 설명
owner string Required

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

repo string Required

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

ref string Required

The Git reference. For more information, see "Git References" in the Git documentation.

"List matching references"에 대한 HTTP 응답 상태 코드

상태 코드설명
200

OK

409

Conflict

"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" repository permissions (read)

공용 리소스만 요청되는 경우 인증 또는 앞서 언급한 권한 없이 이 엔드포인트를 사용할 수 있습니다.

"Get a reference"에 대한 매개 변수

머리글
속성, 형식, 설명
accept string

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

경로 매개 변수
속성, 형식, 설명
owner string Required

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

repo string Required

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

ref string Required

The Git reference. For more information, see "Git References" in the Git documentation.

"Get a reference"에 대한 HTTP 응답 상태 코드

상태 코드설명
200

OK

404

Resource not found

409

Conflict

"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" 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 Required

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

repo string Required

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

본문 매개 변수
속성, 형식, 설명
ref string Required

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 Required

The SHA1 value for this reference.

"Create a reference"에 대한 HTTP 응답 상태 코드

상태 코드설명
201

Created

409

Conflict

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

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

"Update a reference"에 대한 세분화된 액세스 토큰

이 엔드포인트는 다음 세분화된 토큰 형식에서 작동합니다.:

세분화된 토큰에는 다음 권한 집합 중 하나 이상이 있어야 합니다.:

  • "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 Required

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

repo string Required

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

ref string Required

The Git reference. For more information, see "Git References" in the Git documentation.

본문 매개 변수
속성, 형식, 설명
sha string Required

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

409

Conflict

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

Deletes the provided reference.

"Delete a reference"에 대한 세분화된 액세스 토큰

이 엔드포인트는 다음 세분화된 토큰 형식에서 작동합니다.:

세분화된 토큰에는 다음 권한 집합이 있어야 합니다.:

  • "Contents" repository permissions (write)

"Delete a reference"에 대한 매개 변수

머리글
속성, 형식, 설명
accept string

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

경로 매개 변수
속성, 형식, 설명
owner string Required

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

repo string Required

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

ref string Required

The Git reference. For more information, see "Git References" in the Git documentation.

"Delete a reference"에 대한 HTTP 응답 상태 코드

상태 코드설명
204

No Content

409

Conflict

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