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

用于源代码导入的 REST API 端点

使用 REST API 从 Git 源代码仓库启动导入。

关于源代码导入

警告：由于使用率极低且存在替代方案，源代码导入 API 已被弃用，自 2024 年 4 月 12 日起不再可用。有关更多详细信息和替代方案，请参阅 变更日志。

您可以使用这些端点从托管在其他服务的 Git 仓库启动导入。这与 GitHub 导入器功能相同。有关更多信息，请参阅“使用 GitHub 导入器导入仓库”。典型的源代码导入将启动导入，然后（可选）更新作者和/或更新使用 Git LFS 的首选项（如果导入中存在大型文件）。您还可以创建一个 Webhook，用于监听 RepositoryImportEvent，以了解导入的状态。

这些端点仅支持使用个人访问令牌（经典）进行身份验证。有关更多信息，请参阅“管理您的个人访问令牌”。

下图提供了更详细的示例

+---------+                     +--------+                              +---------------------+
| Tooling |                     | GitHub |                              | Original Repository |
+---------+                     +--------+                              +---------------------+
     |                              |                                              |
     |  Start import                |                                              |
     |----------------------------->|                                              |
     |                              |                                              |
     |                              |  Download source data                        |
     |                              |--------------------------------------------->|
     |                              |                        Begin streaming data  |
     |                              |<---------------------------------------------|
     |                              |                                              |
     |  Get import progress         |                                              |
     |----------------------------->|                                              |
     |       "status": "importing"  |                                              |
     |<-----------------------------|                                              |
     |                              |                                              |
     |  Get commit authors          |                                              |
     |----------------------------->|                                              |
     |                              |                                              |
     |  Map a commit author         |                                              |
     |----------------------------->|                                              |
     |                              |                                              |
     |                              |                                              |
     |                              |                       Finish streaming data  |
     |                              |<---------------------------------------------|
     |                              |                                              |
     |                              |  Rewrite commits with mapped authors         |
     |                              |------+                                       |
     |                              |      |                                       |
     |                              |<-----+                                       |
     |                              |                                              |
     |                              |  Update repository on GitHub                 |
     |                              |------+                                       |
     |                              |      |                                       |
     |                              |<-----+                                       |
     |                              |                                              |
     |  Map a commit author         |                                              |
     |----------------------------->|                                              |
     |                              |  Rewrite commits with mapped authors         |
     |                              |------+                                       |
     |                              |      |                                       |
     |                              |<-----+                                       |
     |                              |                                              |
     |                              |  Update repository on GitHub                 |
     |                              |------+                                       |
     |                              |      |                                       |
     |                              |<-----+                                       |
     |                              |                                              |
     |  Get large files             |                                              |
     |----------------------------->|                                              |
     |                              |                                              |
     |  opt_in to Git LFS           |                                              |
     |----------------------------->|                                              |
     |                              |  Rewrite commits for large files             |
     |                              |------+                                       |
     |                              |      |                                       |
     |                              |<-----+                                       |
     |                              |                                              |
     |                              |  Update repository on GitHub                 |
     |                              |------+                                       |
     |                              |      |                                       |
     |                              |<-----+                                       |
     |                              |                                              |
     |  Get import progress         |                                              |
     |----------------------------->|                                              |
     |        "status": "complete"  |                                              |
     |<-----------------------------|                                              |
     |                              |                                              |
     |                              |                                              |

获取导入状态

查看导入的进度。

警告：由于使用率极低且存在替代方案，此端点已弃用，并将于 2024 年 4 月 12 日协调世界时 00:00 起不再可用。有关更多详细信息和替代方案，请参阅 变更日志。

导入状态

本节包含有关导入进度响应中 status 字段的可能值的详细信息。

没有错误的导入将按以下步骤进行

  • detecting - 由于请求未包含 vcs 参数，因此导入的“检测”步骤正在进行中。导入正在识别 URL 中存在的源代码控制类型。
  • importing - 导入的“原始”步骤正在进行中。这是从原始仓库获取提交数据的地方。导入进度响应将包含 commit_count（将导入的原始提交总数）和 percent（0 - 100，导入的当前进度）。
  • mapping - 导入的“重写”步骤正在进行中。这是将 SVN 分支转换为 Git 分支以及应用作者更新的地方。导入进度响应不包含进度信息。
  • pushing - 导入的“推送”步骤正在进行中。这是导入器更新 GitHub 上的仓库的地方。导入进度响应将包含 push_percent，这是 git push 在“写入对象”时报告的百分比值。
  • complete - 导入已完成，仓库已准备好在 GitHub 上。

如果出现问题，您将在 status 字段中看到以下之一：

  • auth_failed - 导入需要身份验证才能连接到原始仓库。要更新导入的身份验证，请参阅 更新导入 部分。
  • error - 导入遇到错误。导入进度响应将包含 failed_step 和错误消息。请联系 GitHub 支持 获取更多信息。
  • detection_needs_auth - 导入器需要源仓库的身份验证才能继续检测。要更新导入的身份验证，请参阅 更新导入 部分。
  • detection_found_nothing - 导入器在 URL 中未识别出任何源代码控制。要解决此问题，请 取消导入 并使用正确的 URL 重试。
  • detection_found_multiple - 导入器在提供的 URL 中找到了多个项目或仓库。在这种情况下，导入进度响应还将包含一个 project_choices 字段，其值为可能的项目选择。要更新项目选择，请参阅 更新导入 部分。

project_choices 字段

当在提供的 URL 中找到多个项目时，响应哈希将包含一个 project_choices 字段，其值为一个哈希数组，每个哈希代表一个项目选择。项目哈希的精确键/值对将根据版本控制类型而有所不同。

Git LFS 相关字段

本节包含有关导入进度响应中可能存在的 Git LFS 相关字段的详细信息。

  • use_lfs - 描述导入是否已选择使用或不使用 Git LFS。该值可以是 opt_in、opt_out 或 undecided（如果未采取任何操作）。
  • has_large_files - 在导入步骤中是否发现超过 100MB 的文件，布尔值。
  • large_files_size - 在源代码库中发现的超过 100MB 文件的总大小（以 GB 为单位）。
  • large_files_count - 在源代码库中发现的超过 100MB 文件的总数。要查看这些文件的列表，请发出“获取大型文件”请求。

用于“获取导入状态”的细粒度访问令牌

此端点与以下细粒度令牌类型一起使用

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

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

“获取导入状态”的参数

标头
accept string

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

路径参数
owner string 必需

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

repo string 必需

存储库的名称，不包含.git扩展名。名称不区分大小写。

“获取导入状态”的 HTTP 响应状态代码

状态代码描述
200

OK

404

资源未找到

503

由于服务维护中，不可用。

“获取导入状态”的代码示例

请求示例

get/repos/{owner}/{repo}/import
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/import

响应

状态：200
{ "vcs": "subversion", "use_lfs": true, "vcs_url": "http://svn.mycompany.com/svn/myproject", "status": "complete", "status_text": "已完成", "has_large_files": true, "large_files_size": 132331036, "large_files_count": 1, "authors_count": 4, "url": "https://api.github.com/repos/octocat/socm/import", "html_url": "https://import.github.com/octocat/socm/import", "authors_url": "https://api.github.com/repos/octocat/socm/import/authors", "repository_url": "https://api.github.com/repos/octocat/socm" }

开始导入

使用 GitHub Importer 将源代码导入到 GitHub 仓库。不支持将代码导入到启用了 GitHub Actions 的 GitHub 仓库，这将返回状态码为 422 Unprocessable Entity 的响应。

警告：由于使用率极低且存在替代方案，此端点已弃用，并将于 2024 年 4 月 12 日协调世界时 00:00 起不再可用。有关更多详细信息和替代方案，请参阅 变更日志。

用于“开始导入”的细粒度访问令牌

此端点与以下细粒度令牌类型一起使用

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

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

用于“开始导入”的参数

标头
accept string

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

路径参数
owner string 必需

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

repo string 必需

存储库的名称，不包含.git扩展名。名称不区分大小写。

主体参数
vcs_url 字符串 必需

源代码仓库的 URL。

vcs 字符串

源代码管理系统类型。如果没有此参数，导入作业将需要额外的时间来检测 VCS 类型，然后再开始导入。此检测步骤将反映在响应中。

可以是以下之一： subversion, git, mercurial, tfvc

vcs_username 字符串

如果需要身份验证，则为 vcs_url 提供的用户名。

vcs_password 字符串

如果需要身份验证，则为 vcs_url 提供的密码。

tfvc_project 字符串

对于 tfvc 导入，要导入的项目的名称。

用于“开始导入”的 HTTP 响应状态码

状态代码描述
201

已创建

404

资源未找到

422

验证失败，或端点已被滥用。

503

由于服务维护中，不可用。

用于“开始导入”的代码示例

请求示例

put/repos/{owner}/{repo}/import
curl -L \ -X PUT \ -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/import \ -d '{"vcs":"subversion","vcs_url":"http://svn.mycompany.com/svn/myproject","vcs_username":"octocat","vcs_password":"secret"}'

响应

状态：201
{ "vcs": "subversion", "use_lfs": true, "vcs_url": "http://svn.mycompany.com/svn/myproject", "status": "importing", "status_text": "正在导入...", "has_large_files": false, "large_files_size": 0, "large_files_count": 0, "authors_count": 0, "commit_count": 1042, "url": "https://api.github.com/repos/octocat/socm/import", "html_url": "https://import.github.com/octocat/socm/import", "authors_url": "https://api.github.com/repos/octocat/socm/import/authors", "repository_url": "https://api.github.com/repos/octocat/socm" }

更新导入

可以通过在 API 请求中传递适当的参数来更新导入的凭据或项目选择。如果未提供参数，则导入将重新启动。

某些服务器（例如 TFS 服务器）可以在单个 URL 中拥有多个项目。在这些情况下，导入进度将具有状态 detection_found_multiple，并且导入进度响应将包含一个 project_choices 数组。您可以通过在更新请求中提供 project_choices 数组中的一个对象来选择要导入的项目。

警告：由于使用率极低且存在替代方案，此端点已弃用，并将于 2024 年 4 月 12 日协调世界时 00:00 起不再可用。有关更多详细信息和替代方案，请参阅 变更日志。

用于“更新导入”的细粒度访问令牌

此端点与以下细粒度令牌类型一起使用

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

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

“更新导入”的参数

标头
accept string

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

路径参数
owner string 必需

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

repo string 必需

存储库的名称，不包含.git扩展名。名称不区分大小写。

主体参数
vcs_username 字符串

提供给源存储库的用户名。

vcs_password 字符串

提供给源存储库的密码。

vcs 字符串

您要从中迁移的版本控制系统类型。

可以是以下之一： subversion, tfvc, git, mercurial

tfvc_project 字符串

对于 tfvc 导入，要导入的项目的名称。

“更新导入”的 HTTP 响应状态代码

状态代码描述
200

OK

503

由于服务维护中，不可用。

“更新导入”的代码示例

请求示例

补丁/repos/{owner}/{repo}/import
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/import \ -d '{"vcs_username":"octocat","vcs_password":"secret"}'

示例 1

状态：200
{ "vcs": "subversion", "use_lfs": true, "vcs_url": "http://svn.mycompany.com/svn/myproject", "status": "detecting", "url": "https://api.github.com/repos/octocat/socm/import", "html_url": "https://import.github.com/octocat/socm/import", "authors_url": "https://api.github.com/repos/octocat/socm/import/authors", "repository_url": "https://api.github.com/repos/octocat/socm" }

取消导入

停止导入仓库。

警告：由于使用率极低且存在替代方案，此端点已弃用，并将于 2024 年 4 月 12 日协调世界时 00:00 起不再可用。有关更多详细信息和替代方案，请参阅 变更日志。

“取消导入”的细粒度访问令牌

此端点与以下细粒度令牌类型一起使用

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

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

“取消导入”的参数

标头
accept string

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

路径参数
owner string 必需

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

repo string 必需

存储库的名称，不包含.git扩展名。名称不区分大小写。

“取消导入”的 HTTP 响应状态码

状态代码描述
204

无内容

503

由于服务维护中，不可用。

“取消导入”的代码示例

请求示例

delete/repos/{owner}/{repo}/import
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/import

响应

状态：204

获取提交作者

每种源代码管理系统以不同的方式表示作者。例如，Git 提交作者有显示名称和电子邮件地址，而 Subversion 提交作者只有用户名。GitHub Importer 会使作者信息有效，但作者可能不正确。例如，它会将裸 Subversion 用户名 hubot 更改为类似 hubot <hubot@12341234-abab-fefe-8787-fedcba987654> 的内容。

此端点和 映射提交作者 端点允许您提供正确的 Git 作者信息。

警告：由于使用率极低且存在替代方案，此端点已弃用，并将于 2024 年 4 月 12 日协调世界时 00:00 起不再可用。有关更多详细信息和替代方案，请参阅 变更日志。

“获取提交作者”的细粒度访问令牌

此端点与以下细粒度令牌类型一起使用

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

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

“获取提交作者”的参数

标头
accept string

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

路径参数
owner string 必需

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

repo string 必需

存储库的名称，不包含.git扩展名。名称不区分大小写。

查询参数
since integer

用户 ID。仅返回 ID 大于此 ID 的用户。

“获取提交作者”的 HTTP 响应状态码

状态代码描述
200

OK

404

资源未找到

503

由于服务维护中，不可用。

“获取提交作者”的代码示例

请求示例

get/repos/{owner}/{repo}/import/authors
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/import/authors

响应

状态：200
[ { "id": 2268557, "remote_id": "nobody@fc7da526-431c-80fe-3c8c-c148ff18d7ef", "remote_name": "nobody", "email": "[email protected]", "name": "Hubot", "url": "https://api.github.com/repos/octocat/socm/import/authors/2268557", "import_url": "https://api.github.com/repos/octocat/socm/import" }, { "id": 2268558, "remote_id": "svner@fc7da526-431c-80fe-3c8c-c148ff18d7ef", "remote_name": "svner", "email": "svner@fc7da526-431c-80fe-3c8c-c148ff18d7ef", "name": "svner", "url": "https://api.github.com/repos/octocat/socm/import/authors/2268558", "import_url": "https://api.github.com/repos/octocat/socm/import" }, { "id": 2268559, "remote_id": "[email protected]@fc7da526-431c-80fe-3c8c-c148ff18d7ef", "remote_name": "[email protected]", "email": "[email protected]@fc7da526-431c-80fe-3c8c-c148ff18d7ef", "name": "[email protected]", "url": "https://api.github.com/repos/octocat/socm/import/authors/2268559", "import_url": "https://api.github.com/repos/octocat/socm/import" } ]

映射提交作者

更新导入的作者身份。在将新的提交推送到存储库之前，您的应用程序可以随时继续更新作者。

警告：由于使用率极低且存在替代方案，此端点已弃用，并将于 2024 年 4 月 12 日协调世界时 00:00 起不再可用。有关更多详细信息和替代方案，请参阅 变更日志。

“映射提交作者”的细粒度访问令牌

此端点与以下细粒度令牌类型一起使用

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

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

“映射提交作者”的参数

标头
accept string

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

路径参数
owner string 必需

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

repo string 必需

存储库的名称，不包含.git扩展名。名称不区分大小写。

author_id 整数 必需
主体参数
email 字符串

新的 Git 作者电子邮件。

name 字符串

新的 Git 作者姓名。

“映射提交作者”的 HTTP 响应状态代码

状态代码描述
200

OK

404

资源未找到

422

验证失败，或端点已被滥用。

503

由于服务维护中，不可用。

“映射提交作者”的代码示例

请求示例

补丁/repos/{owner}/{repo}/import/authors/{author_id}
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/import/authors/AUTHOR_ID \ -d '{"email":"[email protected]","name":"Hubot the Robot"}'

响应

状态：200
{ "id": 2268557, "remote_id": "nobody@fc7da526-431c-80fe-3c8c-c148ff18d7ef", "remote_name": "nobody", "email": "[email protected]", "name": "Hubot", "url": "https://api.github.com/repos/octocat/socm/import/authors/2268557", "import_url": "https://api.github.com/repos/octocat/socm/import" }

获取大文件

列出导入过程中发现的超过 100 MB 的文件

警告：由于使用率极低且存在替代方案，此端点已弃用，并将于 2024 年 4 月 12 日协调世界时 00:00 起不再可用。有关更多详细信息和替代方案，请参阅 变更日志。

“获取大文件”的细粒度访问令牌

此端点与以下细粒度令牌类型一起使用

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

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

获取大型文件参数

标头
accept string

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

路径参数
owner string 必需

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

repo string 必需

存储库的名称，不包含.git扩展名。名称不区分大小写。

获取大型文件的 HTTP 响应状态码

状态代码描述
200

OK

503

由于服务维护中，不可用。

获取大型文件的代码示例

请求示例

get/repos/{owner}/{repo}/import/large_files
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/import/large_files

响应

状态：200
[ { "ref_name": "refs/heads/master", "path": "foo/bar/1", "oid": "d3d9446802a44259755d38e6d163e820", "size": 10485760 }, { "ref_name": "refs/heads/master", "path": "foo/bar/2", "oid": "6512bd43d9caa6e02c990b0a82652dca", "size": 11534336 }, { "ref_name": "refs/heads/master", "path": "foo/bar/3", "oid": "c20ad4d76fe97759aa27a0c99bff6710", "size": 12582912 } ]

更新 Git LFS 偏好设置

您可以从 Subversion、Mercurial 和 TFS 导入包含大于 100MB 文件的仓库。此功能由 Git LFS 提供支持。

您可以在我们的帮助网站上了解有关 LFS 功能和处理大型文件的更多信息 on our help site.

警告：由于使用率极低且存在替代方案，此端点已弃用，并将于 2024 年 4 月 12 日协调世界时 00:00 起不再可用。有关更多详细信息和替代方案，请参阅 变更日志。

更新 Git LFS 偏好设置的细粒度访问令牌

此端点与以下细粒度令牌类型一起使用

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

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

更新 Git LFS 偏好设置的参数

标头
accept string

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

路径参数
owner string 必需

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

repo string 必需

存储库的名称，不包含.git扩展名。名称不区分大小写。

主体参数
use_lfs string 必需

是否在导入期间存储大型文件。opt_in 表示将使用 Git LFS 存储大型文件。opt_out 表示在导入期间将删除大型文件。

可以是以下之一：: opt_in, opt_out

更新 Git LFS 偏好设置的 HTTP 响应状态码

状态代码描述
200

OK

422

验证失败，或端点已被滥用。

503

由于服务维护中，不可用。

更新 Git LFS 偏好设置的代码示例

请求示例

patch/repos/{owner}/{repo}/import/lfs
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/import/lfs \ -d '{"use_lfs":"opt_in"}'

响应

状态：200
{ "vcs": "subversion", "use_lfs": true, "vcs_url": "http://svn.mycompany.com/svn/myproject", "status": "complete", "status_text": "已完成", "has_large_files": true, "large_files_size": 132331036, "large_files_count": 1, "authors_count": 4, "url": "https://api.github.com/repos/octocat/socm/import", "html_url": "https://import.github.com/octocat/socm/import", "authors_url": "https://api.github.com/repos/octocat/socm/import/authors", "repository_url": "https://api.github.com/repos/octocat/socm" }