如何通过Git REST API为指定Commit ID创建标签

我来帮你梳理正确的操作步骤——你之前的调用其实只完成了一半，因为GitHub REST API创建标签需要两个关键步骤：先创建标签对象，再创建指向该对象的引用，这样标签才会在仓库中正常显示。

步骤1：创建附注标签对象 #

首先调用POST /repos/{owner}/{repo}/git/tags端点来创建一个附注标签对象（如果要创建轻量标签，可以直接跳过这一步，看步骤2）。

你需要确保请求体是严格的JSON格式（注意必须用双引号，不能用单引号），并且带上有效的认证头。示例请求如下：

curl -X POST \
  https://github.xxx.com/api/v3/repos/sample_org/testrepo1/git/tags \
  -H "Authorization: token YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "release_2018-02-09-135370b-123-testing",
    "message": "Testing tagging code",
    "object": "YOUR_TARGET_COMMIT_SHA",
    "type": "commit",
    "tagger": {
      "name": "Your Full Name",
      "email": "your.email@domain.com",
      "date": "2024-05-20T14:30:00Z"
    }
  }'

• tagger字段是可选的，但添加后会记录标签创建者的信息，更符合Git规范。
• 成功调用后，API会返回一个包含sha字段的响应，这个值是标签对象的SHA，一定要保存下来，下一步要用。

步骤2：创建标签引用（关键！） #

仅仅创建标签对象还不够，你需要创建一个Git引用指向它，这样标签才会出现在仓库的标签列表中。调用POST /repos/{owner}/{repo}/git/refs端点：

curl -X POST \
  https://github.xxx.com/api/v3/repos/sample_org/testrepo1/git/refs \
  -H "Authorization: token YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "refs/tags/release_2018-02-09-135370b-123-testing",
    "sha": "TAG_OBJECT_SHA_FROM_STEP1"
  }'

• ref必须以refs/tags/开头，后面跟你的标签名称，这是Git引用的标准格式。
• 如果是创建轻量标签，可以直接跳过步骤1，把这里的sha换成目标提交的SHA即可，无需创建标签对象。

常见问题排查 #

• 权限不足：确保你的个人访问令牌（PAT）拥有repo权限（私有仓库必须，公共仓库建议也带上）。
• JSON格式错误：之前用单引号的请求体是无效的，必须用双引号包裹键和值，这是JSON的强制要求。
• 标签名重复：如果该标签已经存在，API会返回422错误，你需要先删除旧标签或者更换新的标签名称。
• SHA无效：确认你传入的提交SHA是完整且有效的（通常是40个字符的十六进制字符串）。

内容的提问来源于stack exchange，提问作者Sudarshan