Repository Migration API

The Repository Migration API lets you move a project’s Git repository to a different repository or Git provider without recreating the project. Use these endpoints to send a single request that starts a migration, then poll a status endpoint until the migration is no longer in progress. migrates the project’s working tree to the target repository you specify and updates your project to use the target repository.

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, Azure DevOps, and Bitbucket.

If a repository involved in the migration is hosted on Azure DevOps, GitLab, or Bitbucket, 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.

For details on Azure DevOps access controls, refer to the Microsoft documentation on permissions and access.

GitLab

If the target repository is hosted on GitLab, you must:

Provide the personal access token for a GitLab service account using the Git-Provider-Access-Token request header.
Add the service account to the group, or to the project that the group belongs to—depending on whether it’s a group-level or project-level service account—with the Maintainer role or higher.
Allow force pushes on the target repository. Force pushes aren’t allowed by default. You can allow them at the group level, or configure the setting per-repository in the target repository’s protected branch settings.

Migration requires the service account to have Maintainer access or higher on the target repository, and force pushes must be allowed on it. Without both, can’t complete a MIRROR_PUSH migration.

The Git-Provider-Access-Token header is optional, and is only required when the target repository is hosted on GitLab or Bitbucket.

For information on how to acquire a service account personal access token, see GitLab in the Project Provisioning API.

rotates the personal access token immediately after you provide it, and revokes the original. This means a personal access token can only be used once—if you start a migration more than once, for example after a failed attempt, provide a fresh personal access token each time.

If the source repository (the project’s currently associated repository) is hosted on GitLab, you don’t need to provide a token for it— already holds a valid, automatically rotated personal access token from when the repository was first associated with the project. If that token has expired and was unable to rotate it automatically, manually provide a new one using Manually rotate an expired personal access token before starting the migration.

Bitbucket

If the target repository is hosted on Bitbucket Cloud, you must:

Create a Bitbucket access token with write access to the target repository, then provide it using the Git-Provider-Access-Token request header. A repository access token with the repository:write scope is recommended, because it grants the narrowest access needed. For how to create one, see Create a Bitbucket access token in the Project Provisioning API.
Make sure the target repository allows force pushes. Branch restrictions must not prevent force pushes or history rewrites.

Migration requires a Bitbucket access token with write access to the target repository, and the target repository must allow force pushes. Without both, can’t complete a MIRROR_PUSH migration.

Unlike GitLab, doesn’t rotate the Bitbucket access token—it stores the token exactly as you supply it. If the token has expired or been revoked, can’t authenticate with Bitbucket, and the migration fails. Create a new token and supply it again when you start the migration.

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.

Request headers

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, or a Bitbucket access token. Required only if the target repository is hosted on GitLab or Bitbucket. 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`, `azure-devops`, or `bitbucket`.
`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`; when migrating to GitLab, provide `repositoryId`; when migrating to Bitbucket, provide `workspace` and `repositorySlug`.

Example request

Base URL: POST /v1/projects/{projectId}/repository-migration Replace {projectId} with your project ID. Example request header:

{
  "Authorization": "Bearer ey.abc.jwt"
}

Example request body:

{
  "mode": "MIRROR_PUSH",
  "targetCloneUrl": "https://github.com/acme/new-pipelines.git",
  "targetProvider": "github",
  "targetName": "new-pipelines"
}

To migrate to an Azure DevOps repository, include the 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"
  }
}

If the target repository is hosted on GitLab, include the 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>"
}

Also include the providerParameters object with the repository ID for the target repository:

{
  "mode": "MIRROR_PUSH",
  "targetCloneUrl": "https://gitlab.com/acme/new-pipelines.git",
  "targetProvider": "gitlab",
  "targetName": "new-pipelines",
  "providerParameters": {
    "repositoryId": "87654321"
  }
}

If the target repository is hosted on Bitbucket, include the Git-Provider-Access-Token header in your request, in addition to Authorization:

{
  "Authorization": "Bearer ey.abc.jwt",
  "Git-Provider-Access-Token": "<bitbucket-access-token>"
}

Also include the providerParameters object with the workspace slug and repository slug for the target repository:

{
  "mode": "MIRROR_PUSH",
  "targetCloneUrl": "https://bitbucket.org/acme/new-pipelines.git",
  "targetProvider": "bitbucket",
  "targetName": "new-pipelines",
  "providerParameters": {
    "workspace": "acme",
    "repositorySlug": "new-pipelines"
  }
}

Example success response:

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

Example success response:

HTTP 200 OK

{
  "migrationId": "11111111-2222-3333-4444-555555555555",
  "status": "IN_PROGRESS",
  "detail": "Cloning source repository"
}

The response contains the following fields:

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.

Overview

Endpoints

Prerequisites

Azure DevOps

GitLab

Bitbucket

Migration modes

Start a repository migration

Request headers

Request fields

Example request

Check migration status

Example request

Error responses

​Prerequisites

​Azure DevOps

​GitLab

​Bitbucket

​Migration modes

​Start a repository migration

​Request headers

​Request fields

​Example request

​Check migration status

​Example request

​Error responses

Prerequisites

Azure DevOps

GitLab

Bitbucket

Migration modes

Start a repository migration

Request headers

Request fields

Example request

Check migration status

Example request

Error responses