ソースインポート用の REST API エンドポイント

ソースのインポートについて

Warning

使用レベルが非常に低く、代替手段が使用可能であるため、ソースインポート API は廃止段階になっています。詳細と代替手段については、変更ログを参照してください。

これらのエンドポイントを使用して、別のサービスでホストされている Git リポジトリからインポートを開始できます。これは、GitHub Importer と同じ機能です。詳しくは、「GitHub Importer でリポジトリをインポートする」をご覧ください。一般的なソースのインポートでは、インポートを開始した後、(必要に応じて) 作成者を更新したり、インポートに大きいファイルが存在する場合に Git LFS の使用の設定を更新したりします。また、RepositoryImportEvent をリッスンしてインポートの状態を確認する Webhook を作成することもできます。

Note

これらのエンドポイントでは、personal access token (classic) を使う認証のみがサポートされます。詳しくは、「個人用アクセストークンを管理する」を参照してください。

次の図では、さらに詳細な例を示します。

+---------+                     +--------+                              +---------------------+
| 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"  |                                              |
     |<-----------------------------|                                              |
     |                              |                                              |
     |                              |                                              |

Get an import status

View the progress of an import.

Warning

Endpoint closing down notice: Due to very low levels of usage and available alternatives, this endpoint is closing down and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the changelog.

Import status

This section includes details about the possible values of the status field of the Import Progress response.

An import that does not have errors will progress through these steps:

detecting - the "detection" step of the import is in progress because the request did not include a vcs parameter. The import is identifying the type of source control present at the URL.
importing - the "raw" step of the import is in progress. This is where commit data is fetched from the original repository. The import progress response will include commit_count (the total number of raw commits that will be imported) and percent (0 - 100, the current progress through the import).
mapping - the "rewrite" step of the import is in progress. This is where SVN branches are converted to Git branches, and where author updates are applied. The import progress response does not include progress information.
pushing - the "push" step of the import is in progress. This is where the importer updates the repository on GitHub. The import progress response will include push_percent, which is the percent value reported by git push when it is "Writing objects".
complete - the import is complete, and the repository is ready on GitHub.

If there are problems, you will see one of these in the status field:

auth_failed - the import requires authentication in order to connect to the original repository. To update authentication for the import, please see the Update an import section.
error - the import encountered an error. The import progress response will include the failed_step and an error message. Contact GitHub Support for more information.
detection_needs_auth - the importer requires authentication for the originating repository to continue detection. To update authentication for the import, please see the Update an import section.
detection_found_nothing - the importer didn't recognize any source control at the URL. To resolve, Cancel the import and retry with the correct URL.
detection_found_multiple - the importer found several projects or repositories at the provided URL. When this is the case, the Import Progress response will also include a project_choices field with the possible project choices as values. To update project choice, please see the Update an import section.

The project_choices field

When multiple projects are found at the provided URL, the response hash will include a project_choices field, the value of which is an array of hashes each representing a project choice. The exact key/value pairs of the project hashes will differ depending on the version control type.

Git LFS related fields

This section includes details about Git LFS related fields that may be present in the Import Progress response.

use_lfs - describes whether the import has been opted in or out of using Git LFS. The value can be opt_in, opt_out, or undecided if no action has been taken.
has_large_files - the boolean value describing whether files larger than 100MB were found during the importing step.
large_files_size - the total size in gigabytes of files larger than 100MB found in the originating repository.
large_files_count - the total number of files larger than 100MB found in the originating repository. To see a list of these files, make a "Get Large Files" request.

"Get an import status" のきめ細かいアクセストークン

このエンドポイントは、次の粒度の細かいトークンの種類で動作します:

粒度の細かいトークンには次のアクセス許可セットが設定されている必要があります:

"Contents" repository permissions (read)

"Get an import status" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.

パスパラメーター
名前, Type, 説明
`owner` string 必須 The account owner of the repository. The name is not case sensitive.
`repo` string 必須 The name of the repository without the `.git` extension. The name is not case sensitive.

"Get an import status" の HTTP 応答状態コード

状態コード	説明
`200`	OK
`404`	Resource not found
`503`	Unavailable due to service under maintenance.

"Get an import status" のコードサンプル

要求の例

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

Response

Status: 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"
}

Start an import

Start a source import to a GitHub repository using GitHub Importer. Importing into a GitHub repository with GitHub Actions enabled is not supported and will return a status 422 Unprocessable Entity response.

Warning

Endpoint closing down notice: Due to very low levels of usage and available alternatives, this endpoint is closing down and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the changelog.

"Start an import" のきめ細かいアクセストークン

このエンドポイントは、次の粒度の細かいトークンの種類で動作します:

粒度の細かいトークンには次のアクセス許可セットが設定されている必要があります:

"Contents" repository permissions (write)

"Start an import" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.

パスパラメーター
名前, Type, 説明
`owner` string 必須 The account owner of the repository. The name is not case sensitive.
`repo` string 必須 The name of the repository without the `.git` extension. The name is not case sensitive.

本文のパラメーター
名前, Type, 説明
`vcs_url` string 必須 The URL of the originating repository.
`vcs` string The originating VCS type. Without this parameter, the import job will take additional time to detect the VCS type before beginning the import. This detection step will be reflected in the response. 次のいずれかにできます: `subversion`, `git`, `mercurial`, `tfvc`
`vcs_username` string If authentication is required, the username to provide to `vcs_url`.
`vcs_password` string If authentication is required, the password to provide to `vcs_url`.
`tfvc_project` string For a tfvc import, the name of the project that is being imported.

"Start an import" の HTTP 応答状態コード

状態コード	説明
`201`	Created
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.
`503`	Unavailable due to service under maintenance.

"Start an import" のコードサンプル

要求の例

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"}'

Response

Status: 201

{
  "vcs": "subversion",
  "use_lfs": true,
  "vcs_url": "http://svn.mycompany.com/svn/myproject",
  "status": "importing",
  "status_text": "Importing...",
  "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"
}

Update an import

An import can be updated with credentials or a project choice by passing in the appropriate parameters in this API request. If no parameters are provided, the import will be restarted.

Some servers (e.g. TFS servers) can have several projects at a single URL. In those cases the import progress will have the status detection_found_multiple and the Import Progress response will include a project_choices array. You can select the project to import by providing one of the objects in the project_choices array in the update request.

Warning

Endpoint closing down notice: Due to very low levels of usage and available alternatives, this endpoint is closing down and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the changelog.

"Update an import" のきめ細かいアクセストークン

このエンドポイントは、次の粒度の細かいトークンの種類で動作します:

粒度の細かいトークンには次のアクセス許可セットが設定されている必要があります:

"Contents" repository permissions (write)

"Update an import" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.

パスパラメーター
名前, Type, 説明
`owner` string 必須 The account owner of the repository. The name is not case sensitive.
`repo` string 必須 The name of the repository without the `.git` extension. The name is not case sensitive.

本文のパラメーター
名前, Type, 説明
`vcs_username` string The username to provide to the originating repository.
`vcs_password` string The password to provide to the originating repository.
`vcs` string The type of version control system you are migrating from. 次のいずれかにできます: `subversion`, `tfvc`, `git`, `mercurial`
`tfvc_project` string For a tfvc import, the name of the project that is being imported.

"Update an import" の HTTP 応答状態コード

状態コード	説明
`200`	OK
`503`	Unavailable due to service under maintenance.

"Update an import" のコードサンプル

要求の例

Select the example type

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"}'

Example 1

Status: 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"
}

Cancel an import

Stop an import for a repository.

Warning

Endpoint closing down notice: Due to very low levels of usage and available alternatives, this endpoint is closing down and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the changelog.

"Cancel an import" のきめ細かいアクセストークン

このエンドポイントは、次の粒度の細かいトークンの種類で動作します:

粒度の細かいトークンには次のアクセス許可セットが設定されている必要があります:

"Contents" repository permissions (write)

"Cancel an import" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.

パスパラメーター
名前, Type, 説明
`owner` string 必須 The account owner of the repository. The name is not case sensitive.
`repo` string 必須 The name of the repository without the `.git` extension. The name is not case sensitive.

"Cancel an import" の HTTP 応答状態コード

状態コード	説明
`204`	No Content
`503`	Unavailable due to service under maintenance.

"Cancel an import" のコードサンプル

要求の例

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

Response

Status: 204

Get commit authors

Each type of source control system represents authors in a different way. For example, a Git commit author has a display name and an email address, but a Subversion commit author just has a username. The GitHub Importer will make the author information valid, but the author might not be correct. For example, it will change the bare Subversion username hubot into something like hubot <hubot@12341234-abab-fefe-8787-fedcba987654>.

This endpoint and the Map a commit author endpoint allow you to provide correct Git author information.

Warning

Endpoint closing down notice: Due to very low levels of usage and available alternatives, this endpoint is closing down and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the changelog.

"Get commit authors" のきめ細かいアクセストークン

このエンドポイントは、次の粒度の細かいトークンの種類で動作します:

粒度の細かいトークンには次のアクセス許可セットが設定されている必要があります:

"Contents" repository permissions (read)

"Get commit authors" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.

パスパラメーター
名前, Type, 説明
`owner` string 必須 The account owner of the repository. The name is not case sensitive.
`repo` string 必須 The name of the repository without the `.git` extension. The name is not case sensitive.

クエリパラメーター
名前, Type, 説明
`since` integer A user ID. Only return users with an ID greater than this ID.

"Get commit authors" の HTTP 応答状態コード

状態コード	説明
`200`	OK
`404`	Resource not found
`503`	Unavailable due to service under maintenance.

"Get commit authors" のコードサンプル

要求の例

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

Response

Status: 200

[
  {
    "id": 2268557,
    "remote_id": "nobody@fc7da526-431c-80fe-3c8c-c148ff18d7ef",
    "remote_name": "nobody",
    "email": "hubot@github.com",
    "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": "svner@example.com@fc7da526-431c-80fe-3c8c-c148ff18d7ef",
    "remote_name": "svner@example.com",
    "email": "svner@example.com@fc7da526-431c-80fe-3c8c-c148ff18d7ef",
    "name": "svner@example.com",
    "url": "https://api.github.com/repos/octocat/socm/import/authors/2268559",
    "import_url": "https://api.github.com/repos/octocat/socm/import"
  }
]

Map a commit author

Update an author's identity for the import. Your application can continue updating authors any time before you push new commits to the repository.

Warning

Endpoint closing down notice: Due to very low levels of usage and available alternatives, this endpoint is closing down and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the changelog.

"Map a commit author" のきめ細かいアクセストークン

このエンドポイントは、次の粒度の細かいトークンの種類で動作します:

粒度の細かいトークンには次のアクセス許可セットが設定されている必要があります:

"Contents" repository permissions (write)

"Map a commit author" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.

パスパラメーター
名前, Type, 説明
`owner` string 必須 The account owner of the repository. The name is not case sensitive.
`repo` string 必須 The name of the repository without the `.git` extension. The name is not case sensitive.
`author_id` integer 必須

本文のパラメーター
名前, Type, 説明
`email` string The new Git author email.
`name` string The new Git author name.

"Map a commit author" の HTTP 応答状態コード

状態コード	説明
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.
`503`	Unavailable due to service under maintenance.

"Map a commit author" のコードサンプル

要求の例

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":"hubot@github.com","name":"Hubot the Robot"}'

Response

Status: 200

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

Get large files

List files larger than 100MB found during the import

Warning

Endpoint closing down notice: Due to very low levels of usage and available alternatives, this endpoint is closing down and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the changelog.

"Get large files" のきめ細かいアクセストークン

このエンドポイントは、次の粒度の細かいトークンの種類で動作します:

粒度の細かいトークンには次のアクセス許可セットが設定されている必要があります:

"Contents" repository permissions (read)

"Get large files" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.

パスパラメーター
名前, Type, 説明
`owner` string 必須 The account owner of the repository. The name is not case sensitive.
`repo` string 必須 The name of the repository without the `.git` extension. The name is not case sensitive.

"Get large files" の HTTP 応答状態コード

状態コード	説明
`200`	OK
`503`	Unavailable due to service under maintenance.

"Get large files" のコードサンプル

要求の例

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

Response

Status: 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
  }
]

Update Git LFS preference

You can import repositories from Subversion, Mercurial, and TFS that include files larger than 100MB. This ability is powered by Git LFS.

You can learn more about our LFS feature and working with large files on our help site.

Warning

Endpoint closing down notice: Due to very low levels of usage and available alternatives, this endpoint is closing down and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the changelog.

"Update Git LFS preference" のきめ細かいアクセストークン

このエンドポイントは、次の粒度の細かいトークンの種類で動作します:

粒度の細かいトークンには次のアクセス許可セットが設定されている必要があります:

"Contents" repository permissions (write)

"Update Git LFS preference" のパラメーター

ヘッダー
名前, Type, 説明
`accept` string Setting to `application/vnd.github+json` is recommended.

パスパラメーター
名前, Type, 説明
`owner` string 必須 The account owner of the repository. The name is not case sensitive.
`repo` string 必須 The name of the repository without the `.git` extension. The name is not case sensitive.

本文のパラメーター
名前, Type, 説明
`use_lfs` string 必須 Whether to store large files during the import. `opt_in` means large files will be stored using Git LFS. `opt_out` means large files will be removed during the import. 次のいずれかにできます: `opt_in`, `opt_out`

"Update Git LFS preference" の HTTP 応答状態コード

状態コード	説明
`200`	OK
`422`	Validation failed, or the endpoint has been spammed.
`503`	Unavailable due to service under maintenance.

"Update Git LFS preference" のコードサンプル

要求の例

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"}'

Response

Status: 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"
}

ソース インポート用の REST API エンドポイント

要求の例

Response

要求の例

Response

要求の例

Example 1

要求の例

Response

要求の例

Response

要求の例

Response

要求の例

Response

要求の例

Response

ソースインポート用の REST API エンドポイント