Skip to main content
O controle de versão da API REST já foi feito. Para obter mais informações, confira "Sobre o controle de versão da API".

Importações de código-fonte

Use a API REST para iniciar uma importação de um repositório de código-fonte do Git, do Subversion, do Mercurial ou do Controle de Versão do Team Foundation.

Sobre as importações de origem

Aviso: o suporte para importação de repositórios do Mercurial, do Subversion e do TFVC (Controle de Versão do Team Foundation) será encerrado em 17 de outubro de 2023. Para obter detalhes, confira o log de alterações.

Você pode usar estes pontos de extremidade para iniciar uma importação de um repositório de código-fonte do Git, do Subversion, do Mercurial ou do Controle de Versão do Team Foundation. Esta é a mesma funcionalidade que a do importador GitHub. Para obter mais informações, confira "Importar um repositório usando o Importador do GitHub". Uma importação de código-fonte típica iniciaria a importação e, em seguida, (opcionalmente) atualizaria os autores e/ou atualizaria a preferência pelo uso do Git LFS se existissem arquivos grandes na importação. Você também pode criar um webhook que escuta no RepositoryImportEvent para descobrir o status da importação.

Esses pontos de extremidade só dão suporte à autenticação por meio de um personal access token (classic). Para obter mais informações, confira "Gerenciar seus tokens de acesso pessoal".

O seguinte diagrama fornece um exemplo mais detalhado:

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

Funciona com GitHub Apps

View the progress of an import.

Warning: Support for importing Mercurial, Subversion and Team Foundation Version Control repositories will end on October 17, 2023. For more details, see changelog. In the coming weeks, we will update these docs to reflect relevant changes to the API and will contact all integrators using the "Source imports" API.

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 Enterprise Cloud. 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 Enterprise Cloud.

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 Enterprise Cloud 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.

Parâmetros para "Get an import status"

Cabeçalhos
Nome, Type, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Type, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

Códigos de status de resposta HTTP para "Get an import status"

Código de statusDescrição
200

OK

404

Resource not found

503

Unavailable due to service under maintenance.

Exemplos de código para "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

Funciona com GitHub Apps

Start a source import to a GitHub Enterprise Cloud repository using GitHub Enterprise Cloud Importer. Importing into a GitHub Enterprise Cloud repository with GitHub Actions enabled is not supported and will return a status 422 Unprocessable Entity response. Warning: Support for importing Mercurial, Subversion and Team Foundation Version Control repositories will end on October 17, 2023. For more details, see changelog. In the coming weeks, we will update these docs to reflect relevant changes to the API and will contact all integrators using the "Source imports" API.

Parâmetros para "Start an import"

Cabeçalhos
Nome, Type, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Type, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

Parâmetros do corpo
Nome, Type, Descrição
vcs_url string Obrigatório

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.

Pode ser um dos: 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.

Códigos de status de resposta HTTP para "Start an import"

Código de statusDescrição
201

Created

404

Resource not found

422

Validation failed, or the endpoint has been spammed.

503

Unavailable due to service under maintenance.

Exemplos de código para "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

Funciona com GitHub Apps

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: Support for importing Mercurial, Subversion and Team Foundation Version Control repositories will end on October 17, 2023. For more details, see changelog. In the coming weeks, we will update these docs to reflect relevant changes to the API and will contact all integrators using the "Source imports" API.

Parâmetros para "Update an import"

Cabeçalhos
Nome, Type, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Type, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

Parâmetros do corpo
Nome, Type, Descrição
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.

Pode ser um dos: subversion, tfvc, git, mercurial

tfvc_project string

For a tfvc import, the name of the project that is being imported.

Códigos de status de resposta HTTP para "Update an import"

Código de statusDescrição
200

OK

503

Unavailable due to service under maintenance.

Exemplos de código para "Update an import"

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

Funciona com GitHub Apps

Stop an import for a repository.

Warning: Support for importing Mercurial, Subversion and Team Foundation Version Control repositories will end on October 17, 2023. For more details, see changelog. In the coming weeks, we will update these docs to reflect relevant changes to the API and will contact all integrators using the "Source imports" API.

Parâmetros para "Cancel an import"

Cabeçalhos
Nome, Type, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Type, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

Códigos de status de resposta HTTP para "Cancel an import"

Código de statusDescrição
204

No Content

503

Unavailable due to service under maintenance.

Exemplos de código para "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

Funciona com GitHub Apps

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 Enterprise Cloud 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: Support for importing Mercurial, Subversion and Team Foundation Version Control repositories will end on October 17, 2023. For more details, see changelog. In the coming weeks, we will update these docs to reflect relevant changes to the API and will contact all integrators using the "Source imports" API.

Parâmetros para "Get commit authors"

Cabeçalhos
Nome, Type, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Type, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

Parâmetros de consulta
Nome, Type, Descrição
since integer

A user ID. Only return users with an ID greater than this ID.

Códigos de status de resposta HTTP para "Get commit authors"

Código de statusDescrição
200

OK

404

Resource not found

503

Unavailable due to service under maintenance.

Exemplos de código para "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

Funciona com GitHub Apps

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: Support for importing Mercurial, Subversion and Team Foundation Version Control repositories will end on October 17, 2023. For more details, see changelog. In the coming weeks, we will update these docs to reflect relevant changes to the API and will contact all integrators using the "Source imports" API.

Parâmetros para "Map a commit author"

Cabeçalhos
Nome, Type, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Type, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

author_id integer Obrigatório
Parâmetros do corpo
Nome, Type, Descrição
email string

The new Git author email.

name string

The new Git author name.

Códigos de status de resposta HTTP para "Map a commit author"

Código de statusDescrição
200

OK

404

Resource not found

422

Validation failed, or the endpoint has been spammed.

503

Unavailable due to service under maintenance.

Exemplos de código para "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

Funciona com GitHub Apps

List files larger than 100MB found during the import

Warning: Support for importing Mercurial, Subversion and Team Foundation Version Control repositories will end on October 17, 2023. For more details, see changelog. In the coming weeks, we will update these docs to reflect relevant changes to the API and will contact all integrators using the "Source imports" API.

Parâmetros para "Get large files"

Cabeçalhos
Nome, Type, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Type, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

Códigos de status de resposta HTTP para "Get large files"

Código de statusDescrição
200

OK

503

Unavailable due to service under maintenance.

Exemplos de código para "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

Funciona com GitHub Apps

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: Support for importing Mercurial, Subversion and Team Foundation Version Control repositories will end on October 17, 2023. For more details, see changelog. In the coming weeks, we will update these docs to reflect relevant changes to the API and will contact all integrators using the "Source imports" API.

Parâmetros para "Update Git LFS preference"

Cabeçalhos
Nome, Type, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Type, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

Parâmetros do corpo
Nome, Type, Descrição
use_lfs string Obrigatório

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.

Pode ser um dos: opt_in, opt_out

Códigos de status de resposta HTTP para "Update Git LFS preference"

Código de statusDescrição
200

OK

422

Validation failed, or the endpoint has been spammed.

503

Unavailable due to service under maintenance.

Exemplos de código para "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" }