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

源代码导入的 REST API 端点

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

关于源代码导入

警告

由于使用率极低且存在替代方案，源代码导入 API 已停止使用。有关更多详细信息和替代方案，请参阅变更日志。

您可以使用这些端点从由其他服务托管的 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 - 布尔值，描述在importing步骤期间是否找到大于 100 MB 的文件。
  • large_files_size - 在源仓库中找到的大于 100 MB 的文件的总大小（以 GB 为单位）。
  • large_files_count - 在源仓库中找到的大于 100 MB 的文件的总数。要查看这些文件的列表，请发出“获取大文件”请求。

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

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

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

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

“获取导入状态”的参数

标头
accept 字符串

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

路径参数
owner 字符串 必填

仓库的账户所有者。名称不区分大小写。

repo 字符串 必填

仓库的名称，不含.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": "Done", "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 字符串

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

路径参数
owner 字符串 必填

仓库的账户所有者。名称不区分大小写。

repo 字符串 必填

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

主体参数
vcs_url 字符串 必填

源仓库的 URL。

vcs 字符串

源 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 字符串

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

路径参数
owner 字符串 必填

仓库的账户所有者。名称不区分大小写。

repo 字符串 必填

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

主体参数
vcs_username 字符串

提供给源仓库的用户名。

vcs_password 字符串

提供给源仓库的密码。

vcs 字符串

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

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

tfvc_project 字符串

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

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

状态代码描述
200

OK

503

由于服务正在维护而不可用。

“更新导入”的代码示例

请求示例

patch/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 字符串

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

路径参数
owner 字符串 必填

仓库的账户所有者。名称不区分大小写。

repo 字符串 必填

仓库的名称，不含.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 字符串

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

路径参数
owner 字符串 必填

仓库的账户所有者。名称不区分大小写。

repo 字符串 必填

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

查询参数
since 整数

用户 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 字符串

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

路径参数
owner 字符串 必填

仓库的账户所有者。名称不区分大小写。

repo 字符串 必填

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

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

新的 Git 作者电子邮件。

name 字符串

新的 Git 作者姓名。

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

状态代码描述
200

OK

404

资源未找到

422

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

503

由于服务正在维护而不可用。

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

请求示例

patch/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 字符串

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

路径参数
owner 字符串 必填

仓库的账户所有者。名称不区分大小写。

repo 字符串 必填

仓库的名称，不含.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 首选项

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

您可以在我们的帮助站点上了解有关我们的 LFS 功能和处理大文件的更多信息 。

警告

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

“更新 Git LFS 首选项”的细粒度访问令牌

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

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

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

“更新 Git LFS 首选项”的参数

标头
accept 字符串

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

路径参数
owner 字符串 必填

仓库的账户所有者。名称不区分大小写。

repo 字符串 必填

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

主体参数
use_lfs 字符串 必填

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

可以是以下之一： opt_in, opt_out

"更新 Git LFS 首选项" 的 HTTP 响应状态码

状态代码描述
200

OK

422

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

503

由于服务正在维护而不可用。

"更新 Git LFS 首选项" 的代码示例

请求示例

修补程序/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": "Done", "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" }