REST API 现在已版本化。 有关更多信息，请参阅“关于 API 版本控制”。

Git 提交的 REST API 端点

使用 REST API 与 GitHub 上 Git 数据库中的提交对象进行交互。

关于 Git 提交

Git 提交是 Git 代码库中文件层次结构（Git 树）和文件内容（Git Blob）的快照。这些端点允许您读取和写入 GitHub 上 Git 数据库中的提交对象。

创建提交

创建一个新的 Git 提交对象。

签名验证对象

响应将包含一个verification对象，该对象描述了验证提交签名的结果。以下字段包含在verification对象中

名称类型描述
verified布尔值指示 GitHub 是否认为此提交中的签名已验证。
reason字符串verified 值的原因。下表列出了可能的值及其含义。
signature字符串从提交中提取的签名。
payload字符串已签名的值。

这些是verification对象中reason的可能值

值描述
expired_key生成签名的密钥已过期。
not_signing_key“签名”标志不在生成签名的 GPG 密钥的用法标志中。
gpgverify_error与签名验证服务通信时出错。
gpgverify_unavailable签名验证服务当前不可用。
unsigned该对象不包含签名。
unknown_signature_type在提交中找到非 PGP 签名。
no_user提交中的committer电子邮件地址未关联任何用户。
unverified_email提交中的committer电子邮件地址与用户关联，但该电子邮件地址在其帐户上未经验证。
bad_email提交中的committer电子邮件地址未包含在生成签名的 PGP 密钥的身份中。
unknown_key生成签名的密钥未在任何用户的帐户中注册。
malformed_signature解析签名时出错。
invalid无法使用签名中找到密钥 ID 的密钥对签名进行加密验证。
valid上述错误均不适用，因此签名被认为已验证。

“创建提交”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “内容”代码库权限（写入）

“创建提交”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
owner 字符串 必填

代码库的帐户所有者。名称不区分大小写。

repo 字符串 必填

代码库的名称，不含.git扩展名。名称不区分大小写。

主体参数
message 字符串 必填

提交消息

tree 字符串 必填

此提交指向的树对象的 SHA

parents 字符串数组

此提交的父提交的完整 SHA。如果省略或为空，则提交将作为根提交写入。对于单个父级，应提供一个包含一个 SHA 的数组；对于合并提交，应提供多个 SHA 的数组。

author 对象

有关提交作者的信息。默认情况下，author将是经过身份验证的用户和当前日期。有关详细信息，请参阅下面的author和committer对象。

name 字符串 必填

提交的作者（或提交者）的名称

email 字符串 必填

提交的作者（或提交者）的电子邮件

date 字符串

指示此提交的创作时间（或提交时间）。这是一个ISO 8601格式的时间戳：YYYY-MM-DDTHH:MM:SSZ。

committer 对象

有关正在进行提交的人员的信息。默认情况下，committer将使用author中设置的信息。有关详细信息，请参阅下面的author和committer对象。

name 字符串

提交的作者（或提交者）的名称

email 字符串

提交的作者（或提交者）的电子邮件

date 字符串

指示此提交的创作时间（或提交时间）。这是一个ISO 8601格式的时间戳：YYYY-MM-DDTHH:MM:SSZ。

signature 字符串

提交的PGP 签名。GitHub 将签名添加到创建的提交的gpgsig标头中。为了使 Git 或 GitHub 可验证提交签名，它必须是对字符串提交的 ASCII 编码的独立 PGP 签名，就像它将被写入对象数据库一样。要传递signature参数，您需要先手动创建一个有效的 PGP 签名，这可能很复杂。您可能会发现使用命令行创建签名提交更容易。

“创建提交”的 HTTP 响应状态代码

状态代码描述
201

已创建

404

资源未找到

409

冲突

422

验证失败，或端点已被垃圾邮件发送。

“创建提交”的代码示例

请求示例

post/repos/{owner}/{repo}/git/commits
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/commits \ -d '{"message":"我的提交信息","author":{"name":"Mona Octocat","email":"[email protected]","date":"2008-07-09T16:13:30+12:00"},"parents":["7d1b31e74ee336d15cbd21741bc88a537ed063a0"],"tree":"827efc6d56897b048c772eb4087f854f46256132","signature":"-----BEGIN PGP SIGNATURE-----\n\niQIzBAABAQAdFiEESn/54jMNIrGSE6Tp6cQjvhfv7nAFAlnT71cACgkQ6cQjvhfv\n7nCWwA//XVqBKWO0zF+bZl6pggvky3Oc2j1pNFuRWZ29LXpNuD5WUGXGG209B0hI\nDkmcGk19ZKUTnEUJV2Xd0R7AW01S/YSub7OYcgBkI7qUE13FVHN5ln1KvH2all2n\n2+JCV1HcJLEoTjqIFZSSu/sMdhkLQ9/NsmMAzpf/iIM0nQOyU4YRex9eD1bYj6nA\nOQPIDdAuaTQj1gFPHYLzM4zJnCqGdRlg0sOM/zC5apBNzIwlgREatOYQSCfCKV7k\nnrU34X8b9BzQaUx48Qa+Dmfn5KQ8dl27RNeWAqlkuWyv3pUauH9UeYW+KyuJeMkU\n+NyHgAsWFaCFl23kCHThbLStMZOYEnGagrd0hnm1TPS4GJkV4wfYMwnI4KuSlHKB\njHl3Js9vNzEUQipQJbgCgTiWvRJoK3ENwBTMVkKHaqT4x9U4Jk/XZB6Q8MA09ezJ\n3QgiTjTAGcum9E9QiJqMYdWQPWkaBIRRz5cET6HPB48YNXAAUsfmuYsGrnVLYbG+\nUpC6I97VybYHTy2O9XSGoaLeMI9CsFn38ycAxxbWagk5mhclNTP5mezIq6wKSwmr\nX11FW3n1J23fWZn5HJMBsRnUCgzqzX3871IqLYHqRJ/bpZ4h20RhTyPj5c/z7QXp\neSakNQMfbbMcljkha+ZMuVQX1K9aRlVqbmv3ZMWh+OijLYVU2bc=\n=5Io4\n-----END PGP SIGNATURE-----\n"}'

响应

状态：201
{ "sha": "7638417db6d59f3c431d3e1f261cc637155684cd", "node_id": "MDY6Q29tbWl0NzYzODQxN2RiNmQ1OWYzYzQzMWQzZTFmMjYxY2M2MzcxNTU2ODRjZA==", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd", "author": { "date": "2014-11-07T22:01:45Z", "name": "Monalisa Octocat", "email": "[email protected]" }, "committer": { "date": "2014-11-07T22:01:45Z", "name": "Monalisa Octocat", "email": "[email protected]" }, "message": "我的提交信息", "tree": { "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/827efc6d56897b048c772eb4087f854f46256132", "sha": "827efc6d56897b048c772eb4087f854f46256132" }, "parents": [ { "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7d1b31e74ee336d15cbd21741bc88a537ed063a0", "sha": "7d1b31e74ee336d15cbd21741bc88a537ed063a0", "html_url": "https://github.com/octocat/Hello-World/commit/7d1b31e74ee336d15cbd21741bc88a537ed063a0" } ], "verification": { "verified": false, "reason": "unsigned", "signature": null, "payload": null }, "html_url": "https://github.com/octocat/Hello-World/commit/7638417db6d59f3c431d3e1f261cc637155684cd" }

获取提交对象

获取 Git 提交对象。

要获取提交的内容，请参阅“获取提交”。

签名验证对象

响应将包含一个verification对象，该对象描述了验证提交签名的结果。以下字段包含在verification对象中

名称类型描述
verified布尔值指示 GitHub 是否认为此提交中的签名已验证。
reason字符串verified 值的原因。下表列出了可能的值及其含义。
signature字符串从提交中提取的签名。
payload字符串已签名的值。

这些是verification对象中reason的可能值

值描述
expired_key生成签名的密钥已过期。
not_signing_key“签名”标志不在生成签名的 GPG 密钥的用法标志中。
gpgverify_error与签名验证服务通信时出错。
gpgverify_unavailable签名验证服务当前不可用。
unsigned该对象不包含签名。
unknown_signature_type在提交中找到非 PGP 签名。
no_user提交中的committer电子邮件地址未关联任何用户。
unverified_email提交中的committer电子邮件地址与用户关联，但该电子邮件地址在其帐户上未经验证。
bad_email提交中的committer电子邮件地址未包含在生成签名的 PGP 密钥的身份中。
unknown_key生成签名的密钥未在任何用户的帐户中注册。
malformed_signature解析签名时出错。
invalid无法使用签名中找到密钥 ID 的密钥对签名进行加密验证。
valid上述错误均不适用，因此签名被认为已验证。

“获取提交对象”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “内容”存储库权限（读取）

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

“获取提交对象”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
owner 字符串 必填

代码库的帐户所有者。名称不区分大小写。

repo 字符串 必填

代码库的名称，不含.git扩展名。名称不区分大小写。

commit_sha 字符串 必填

提交的 SHA。

“获取提交对象”的 HTTP 响应状态代码

状态代码描述
200

确定

404

资源未找到

409

冲突

“获取提交对象”的代码示例

请求示例

获取/repos/{owner}/{repo}/git/commits/{commit_sha}
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/commits/COMMIT_SHA

响应

状态：200
{ "sha": "7638417db6d59f3c431d3e1f261cc637155684cd", "node_id": "MDY6Q29tbWl0NmRjYjA5YjViNTc4NzVmMzM0ZjYxYWViZWQ2OTVlMmU0MTkzZGI1ZQ==", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd", "html_url": "https://github.com/octocat/Hello-World/commit/7638417db6d59f3c431d3e1f261cc637155684cd", "author": { "date": "2014-11-07T22:01:45Z", "name": "Monalisa Octocat", "email": "[email protected]" }, "committer": { "date": "2014-11-07T22:01:45Z", "name": "Monalisa Octocat", "email": "[email protected]" }, "message": "添加了自述文件，因为我是一个优秀的 GitHub 公民", "tree": { "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb", "sha": "691272480426f78a0138979dd3ce63b77f706feb" }, "parents": [ { "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5", "sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5", "html_url": "https://github.com/octocat/Hello-World/commit/7638417db6d59f3c431d3e1f261cc637155684cd" } ], "verification": { "verified": false, "reason": "unsigned", "signature": null, "payload": null } }