Private preview
The Repository Migration API is currently available as a private preview for selected customers. To request access to this feature, contact your Matillion account representative.
- Migration is an asynchronous, long-running operation. Only one migration can run for a project at any time.
- While a migration is in progress, all other Git operations on the project’s repository are blocked until the migration is no longer in progress.
Prerequisites
Before you begin, you need:
- An existing project that has an associated Git repository. To associate a repository with a project, see Initialize Repository.
- A target repository that already exists on the target Git provider. does not create the target repository for you. The supported target providers are GitHub, GitLab, and Azure DevOps.
If a repository involved in the migration is hosted on Azure DevOps or GitLab, complete the additional setup described below for that provider before starting the migration.
Azure DevOps
If either the source or target repository is hosted on Azure DevOps, you must:
- Install the Maia for Azure DevOps application in the Azure tenant that hosts the repository. If the application is already installed in that tenant—for example, because another user has previously connected an Azure DevOps repository to —you can skip this step. Otherwise, follow Installing the Maia app in Azure.
- Add the service principal to the Azure DevOps repository, and grant it explicit Read and Force push (rewrite history, delete branches and tags) permissions.
Migration requires the service principal to have explicit Force push permission on the repository, in addition to Read. Read and Contribute permissions alone are not sufficient—without Force push, can’t complete a MIRROR_PUSH migration.
GitLab
If the target repository is hosted on GitLab, provide the personal access token for a GitLab service account using the Git-Provider-Access-Token request header.
The Git-Provider-Access-Token header is optional, and is only required when the target repository is hosted on GitLab.
Migration modes
Use the mode field to choose how the migration runs. The two modes, MIRROR_PUSH and RECONFIGURE, are explained in the table below.
| Mode | Description |
|---|
MIRROR_PUSH | copies the project’s full working tree—including all branches and tags—to the target repository, then updates the project to use the target. Use this mode to move your project history into an empty target repository. The target clone URL must be different from the project’s current repository. |
RECONFIGURE | updates the project to use the target repository without copying any content to the target repository. Use this mode when the target repository already contains the project’s history—for example, if you have manually mirrored the repository yourself. The target repository must already contain every branch that exists in the project’s working tree. |
Start a repository migration
Use this endpoint to start an asynchronous migration of the project’s Git repository to the target repository. This request returns a migrationId that you can use to track the progress of this migration.
| Header | Required | Description |
|---|
Authorization | Yes | A bearer token used to authenticate the request. |
Git-Provider-Access-Token | No | The personal access token for a GitLab service account. Required only if the target repository is hosted on GitLab. Not required for a GitLab source repository—see GitLab above. |
Request fields
| Field | Required | Description |
|---|
mode | Yes | The migration mode, either MIRROR_PUSH or RECONFIGURE. |
targetCloneUrl | Yes | The clone URL of the target Git repository to migrate to. |
targetProvider | Yes | The Git provider hosting the target repository, one of github, gitlab, or azure-devops. |
targetName | Yes | The display name of the target repository. |
targetEnterpriseOauthId | No | The UUID of the enterprise OAuth connection used to authenticate with the target repository (not required for public or personal repositories). |
providerParameters | No | Provider-specific parameters for the target repository, supplied as key/value pairs. Required for some providers—when migrating to Azure DevOps, provide organization, repositoryId, and tenantId. |
Example request
Base URL: POST /v1/projects/{projectId}/repository-migration
Replace {projectId} with your project ID.
Example request header:
{
"Authorization": "Bearer ey.abc.jwt"
}
{
"mode": "MIRROR_PUSH",
"targetCloneUrl": "https://github.com/acme/new-pipelines.git",
"targetProvider": "github",
"targetName": "new-pipelines"
}
providerParameters object with the organization, repository ID, and tenant ID for the target repository:
{
"mode": "MIRROR_PUSH",
"targetCloneUrl": "https://dev.azure.com/my-azure-organization/my-project/_git/new-pipelines",
"targetProvider": "azure-devops",
"targetName": "new-pipelines",
"providerParameters": {
"organization": "my-azure-organization",
"repositoryId": "existing-repo-id",
"tenantId": "00000000-0000-0000-0000-000000000000"
}
}
Git-Provider-Access-Token header in your request, in addition to Authorization:
{
"Authorization": "Bearer ey.abc.jwt",
"Git-Provider-Access-Token": "<service-account-personal-access-token>"
}
HTTP 202 Accepted
{
"migrationId": "11111111-2222-3333-4444-555555555555"
}
Check migration status
Use this endpoint and the migrationId returned by the previous request to poll the status of a migration. Repeat this request until the status field is no longer IN_PROGRESS.
Example request
Base URL: GET /v1/projects/{projectId}/repository-migration/{migrationId}
Replace {projectId} with your project ID and {migrationId} with the migration ID returned when you started the migration.
Example request header:
{
"Authorization": "Bearer ey.abc.jwt"
}
HTTP 200 OK
{
"migrationId": "11111111-2222-3333-4444-555555555555",
"status": "IN_PROGRESS",
"detail": "Cloning source repository"
}
migrationId: The unique identifier of the repository migration.status: The current status of the migration. The table below explains what each status means.detail: An optional, human-readable description of the migration’s current state, such as a failure reason. This field is only included if this information is available.
| Status | Description |
|---|
IN_PROGRESS | The migration is still running. Continue polling using this endpoint to find out when it finishes. |
COMPLETED | The migration finished successfully. The project is now associated with the target repository. |
FAILED | The migration did not complete. Check the detail field for the reason. |
UNKNOWN | The migration is in a state that the API does not recognize. Retry your request, and contact your Matillion account representative if the status persists. |
Error responses
If an error occurs, the repository migration endpoints return a ProblemDetail response body. The table below explains what the included status code means.
| Status code | Description |
|---|
400 | The request is invalid—for example, the migration mode or target Git provider is unsupported, or the target repository matches the project’s current repository. |
403 | You do not have permission to migrate this project’s repository. |
404 | The project, or the specified migration, could not be found. |
409 | A repository migration is already in progress for this project. Wait for the existing migration to finish before starting another. |
500 | An unexpected error occurred. |
504 | The request timed out. |
