source_imports
Creates, updates, deletes, gets or lists a source_imports resource.
Overview
| Name | source_imports |
| Type | Resource |
| Id | github.migrations.source_imports |
Fields
The following fields are returned by SELECT queries:
- get_import_status
Response
| Name | Datatype | Description |
|---|---|---|
authors_count | integer | |
authors_url | string (uri) | |
commit_count | integer | |
error_message | string | |
failed_step | string | |
has_large_files | boolean | |
html_url | string (uri) | |
import_percent | integer | |
large_files_count | integer | |
large_files_size | integer | |
message | string | |
project_choices | array | |
push_percent | integer | |
repository_url | string (uri) | |
status | string | (auth, error, none, detecting, choose, auth_failed, importing, mapping, waiting_to_push, pushing, complete, setup, unknown, detection_found_multiple, detection_found_nothing, detection_needs_auth) |
status_text | string | |
svc_root | string | |
svn_root | string | |
tfvc_project | string | |
url | string (uri) | |
use_lfs | boolean | |
vcs | string | |
vcs_url | string | The URL of the originating repository. |
Methods
The following methods are available for this resource:
| Name | Accessible by | Required Params | Optional Params | Description |
|---|---|---|---|---|
get_import_status | select | owner, repo | 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. | |
update_import | update | owner, repo | 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. | |
start_import | exec | owner, repo, vcs_url | 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. | |
cancel_import | exec | owner, repo | 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. |
Parameters
Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.
| Name | Datatype | Description |
|---|---|---|
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. |
SELECT examples
- get_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.
SELECT
authors_count,
authors_url,
commit_count,
error_message,
failed_step,
has_large_files,
html_url,
import_percent,
large_files_count,
large_files_size,
message,
project_choices,
push_percent,
repository_url,
status,
status_text,
svc_root,
svn_root,
tfvc_project,
url,
use_lfs,
vcs,
vcs_url
FROM github.migrations.source_imports
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
;
UPDATE examples
- update_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 github.migrations.source_imports
SET
vcs_username = '{{ vcs_username }}',
vcs_password = '{{ vcs_password }}',
vcs = '{{ vcs }}',
tfvc_project = '{{ tfvc_project }}'
WHERE
owner = '{{ owner }}' --required
AND repo = '{{ repo }}' --required
RETURNING
authors_count,
authors_url,
commit_count,
error_message,
failed_step,
has_large_files,
html_url,
import_percent,
large_files_count,
large_files_size,
message,
project_choices,
push_percent,
repository_url,
status,
status_text,
svc_root,
svn_root,
tfvc_project,
url,
use_lfs,
vcs,
vcs_url;
Lifecycle Methods
- start_import
- cancel_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.
EXEC github.migrations.source_imports.start_import
@owner='{{ owner }}' --required,
@repo='{{ repo }}' --required
@@json=
'{
"vcs_url": "{{ vcs_url }}",
"vcs": "{{ vcs }}",
"vcs_username": "{{ vcs_username }}",
"vcs_password": "{{ vcs_password }}",
"tfvc_project": "{{ tfvc_project }}"
}'
;
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.
EXEC github.migrations.source_imports.cancel_import
@owner='{{ owner }}' --required,
@repo='{{ repo }}' --required
;