使用 REST API 与 Git 数据库交互

使用 REST API 读写 GitHub 上 Git 数据库中的原始 Git 对象，以及列出和更新引用（分支头和标签）。

本文内容

概述

这基本上允许你使用 REST API 重新实现大量 Git 功能 - 通过直接在数据库中创建原始对象并更新分支引用，从技术上讲，你几乎可以执行 Git 可以执行的任何操作，而无需安装 Git。

如果 Git 存储库为空或不可用，REST API 将返回 409 Conflict。存储库不可用通常意味着 GitHub 正在创建存储库。对于空存储库，你可以使用 PUT /repos/{owner}/{repo}/contents/{path} REST API 端点创建内容并初始化存储库，以便你可以使用 API 管理 Git 数据库。如果此响应状态持续存在，请通过 GitHub 支持门户 联系我们。

有关 Git 对象数据库的更多信息，请阅读 Pro Git 书籍的 Git 内部结构 章节。

例如，如果你想提交对存储库中文件的更改，你可以

  • 获取当前提交对象
  • 检索它指向的树
  • 检索该树针对特定文件路径拥有的 blob 对象的内容
  • 以某种方式更改内容并发布一个具有该新内容的新 blob 对象，获取 blob SHA
  • 发布一个新的树对象，其中该文件路径指针替换为你的新 blob SHA，获取树 SHA
  • 创建一个新的提交对象，其中当前提交 SHA 作为父级和新的树 SHA，获取提交 SHA
  • 更新分支的引用以指向新的提交 SHA

这看起来可能很复杂，但当你理解该模型时，它实际上非常简单，并且它开启了你可能使用 API 执行的大量操作。

检查拉取请求的可合并性

警告！请不要依赖于直接使用 Git 或 GET /repos/{owner}/{repo}/git/refs/{ref} 更新 merge Git 引用，因为此内容在未经警告的情况下会过时。

使用 API 需要明确请求拉取请求来创建测试合并提交。当你查看 UI 中的拉取请求并且显示“合并”按钮时，或者当你使用 REST API 获取、创建 或 编辑 拉取请求时，将创建测试合并提交。如果没有此请求，merge Git 引用将一直过时，直到下次有人查看拉取请求为止。

如果您当前使用的是生成过时的 merge Git 引用关系的轮询方法，那么 GitHub 建议使用以下步骤来获取默认分支的最新更改

  1. 接收拉取请求 Webhook。
  2. 调用 GET /repos/{owner}/{repo}/pulls/{pull_number} 以启动一个后台作业来创建合并提交候选。
  3. 使用 GET /repos/{owner}/{repo}/pulls/{pull_number} 轮询您的存储库，以查看 mergeable 属性是 true 还是 false。您可以在执行上述步骤后直接使用 Git 或 GET /repos/{owner}/{repo}/git/refs/{ref} 仅更新 merge Git 引用关系。