Git 标记 - GitHub Docs

可通过 Git 标记 API 在 GitHub 上读取标记对象并将其写入 Git 数据库。

关于 Git 标记 API

Git 标记类似于 Git 引用，但它指向的 Git 提交永远不会更改。当您想要指向特定发行版时，Git 标记非常有用。通过这些终结点，可以在 GitHub 上读取标记对象并将其写入 Git 数据库。 Git 标记 API 仅支持带批注的标记对象，不支持轻量级标记。

Create a tag object

使用 GitHub Apps

Note that creating a tag object does not create the reference that makes a tag in Git. If you want to create an annotated tag in Git, you have to do this call to create the tag object, and then create the refs/tags/[tag] reference. If you want to create a lightweight tag, you only have to create the tag reference - this call would be unnecessary.

Signature verification object

The response will include a verification object that describes the result of verifying the commit's signature. The following fields are included in the verification object:

Name	Type	Description
`verified`	`boolean`	Indicates whether GitHub considers the signature in this commit to be verified.
`reason`	`string`	The reason for verified value. Possible values and their meanings are enumerated in table below.
`signature`	`string`	The signature that was extracted from the commit.
`payload`	`string`	The value that was signed.

These are the possible values for reason in the verification object:

Value	Description
`expired_key`	The key that made the signature is expired.
`not_signing_key`	The "signing" flag is not among the usage flags in the GPG key that made the signature.
`gpgverify_error`	There was an error communicating with the signature verification service.
`gpgverify_unavailable`	The signature verification service is currently unavailable.
`unsigned`	The object does not include a signature.
`unknown_signature_type`	A non-PGP signature was found in the commit.
`no_user`	No user was associated with the `committer` email address in the commit.
`unverified_email`	The `committer` email address in the commit was associated with a user, but the email address is not verified on her/his account.
`bad_email`	The `committer` email address in the commit is not included in the identities of the PGP key that made the signature.
`unknown_key`	The key that made the signature has not been registered with any user's account.
`malformed_signature`	There was an error parsing the signature.
`invalid`	The signature could not be cryptographically verified using the key whose key-id was found in the signature.
`valid`	None of the above errors applied, so the signature is considered to be verified.

参数

Headers

Name, Type, Description

acceptstring

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

Path parameters

Name, Type, Description

ownerstringRequired

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

repostringRequired

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

Body parameters

Name, Type, Description

tagstringRequired

The tag's name. This is typically a version (e.g., "v0.0.1").

messagestringRequired

The tag message.

objectstringRequired

The SHA of the git object this is tagging.

typestringRequired

The type of the object we're tagging. Normally this is a commit but it can also be a tree or a blob.

Can be one of: commit, tree, blob

taggerobject

An object with information about the individual creating the tag.

Properties of tagger

Name, Type, Description
`name`stringRequired The name of the author of the tag
`email`stringRequired The email of the author of the tag
`date`string When this object was tagged. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.

HTTP 响应状态代码

状态代码	说明
`201`	Created
`422`	Validation failed, or the endpoint has been spammed.

代码示例

post/repos/{owner}/{repo}/git/tags

curl \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/repos/OWNER/REPO/git/tags \
  -d '{"tag":"v0.0.1","message":"initial version","object":"c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c","type":"commit","tagger":{"name":"Monalisa Octocat","email":"octocat@github.com","date":"2011-06-17T14:53:35-07:00"}}'

Response

Status: 201

{
  "node_id": "MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw==",
  "tag": "v0.0.1",
  "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "message": "initial version",
  "tagger": {
    "name": "Monalisa Octocat",
    "email": "octocat@github.com",
    "date": "2014-11-07T22:01:45Z"
  },
  "object": {
    "type": "commit",
    "sha": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c"
  },
  "verification": {
    "verified": false,
    "reason": "unsigned",
    "signature": null,
    "payload": null
  }
}

Get a tag

使用 GitHub Apps

Signature verification object

The response will include a verification object that describes the result of verifying the commit's signature. The following fields are included in the verification object:

Name	Type	Description
`verified`	`boolean`	Indicates whether GitHub considers the signature in this commit to be verified.
`reason`	`string`	The reason for verified value. Possible values and their meanings are enumerated in table below.
`signature`	`string`	The signature that was extracted from the commit.
`payload`	`string`	The value that was signed.

These are the possible values for reason in the verification object:

Value	Description
`expired_key`	The key that made the signature is expired.
`not_signing_key`	The "signing" flag is not among the usage flags in the GPG key that made the signature.
`gpgverify_error`	There was an error communicating with the signature verification service.
`gpgverify_unavailable`	The signature verification service is currently unavailable.
`unsigned`	The object does not include a signature.
`unknown_signature_type`	A non-PGP signature was found in the commit.
`no_user`	No user was associated with the `committer` email address in the commit.
`unverified_email`	The `committer` email address in the commit was associated with a user, but the email address is not verified on her/his account.
`bad_email`	The `committer` email address in the commit is not included in the identities of the PGP key that made the signature.
`unknown_key`	The key that made the signature has not been registered with any user's account.
`malformed_signature`	There was an error parsing the signature.
`invalid`	The signature could not be cryptographically verified using the key whose key-id was found in the signature.
`valid`	None of the above errors applied, so the signature is considered to be verified.

参数

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository. The name is not case sensitive.
`tag_sha`stringRequired

HTTP 响应状态代码

状态代码	说明
`200`	OK
`404`	Resource not found

代码示例

get/repos/{owner}/{repo}/git/tags/{tag_sha}

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://api.github.com/repos/OWNER/REPO/git/tags/TAG_SHA

Response

Status: 200

{
  "node_id": "MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw==",
  "tag": "v0.0.1",
  "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "message": "initial version",
  "tagger": {
    "name": "Monalisa Octocat",
    "email": "octocat@github.com",
    "date": "2014-11-07T22:01:45Z"
  },
  "object": {
    "type": "commit",
    "sha": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c"
  },
  "verification": {
    "verified": false,
    "reason": "unsigned",
    "signature": null,
    "payload": null
  }
}