Edit

5. Cutover to GitHub

Azure DevOps Services

After the initial sync finishes, your repository is ready for cutover. Complete cutover within 21 days of starting the initial sync.

Important

Cutover typically completes in under 30 minutes, during which the Azure DevOps repository is read-only. While the repository is read-only, pushes and pull request updates are blocked, but users can still browse and clone. Notify all affected teams before you schedule cutover.

Before you schedule cutover

Confirm the following conditions:

  • Incremental syncs are healthy and current.
  • GitHub repository branches, tags, and pull requests are present and correct.
  • All affected teams are notified.
  • Hardcoded Azure DevOps URLs in pipelines, scripts, and tooling are identified for update.

Note

Scheduling, monitoring, and approving cutover use the Azure DevOps CLI. After cutover, you validate the migrated repository in the GitHub portal. For more information, see Complete post-migration tasks.

Schedule cutover

az devops migrations cutover set --org https://dev.azure.com/<org>
                                 --repository-id <repo-guid>
                                 --date "YYYY-MM-DDTHH:MM:SSZ"

Time zone guidance: Append Z for UTC, or use an offset such as -08:00 for Pacific Time. If you omit the time zone, your local time zone is assumed. To avoid ambiguity across teams, include Z or an explicit offset.

Cancel a scheduled cutover

az devops migrations cutover cancel --org https://dev.azure.com/<org>
                                    --repository-id <repo-guid>

Note

The cutover cancel command works only while the migration is still in the Synchronization stage. Once the stage advances to Cutover, the server rejects the cancel request and the CLI returns a non-zero exit code. If you need to stop a cutover that's already in progress, use az devops migrations abandon or contact the ELM team.

What happens during cutover

  1. The Azure DevOps repository is placed into a controlled read-only state.
  2. ELM performs the final synchronization. Remaining deltas are applied to GitHub.
  3. GitHub becomes the authoritative system of record.
  4. A banner appears on the Azure DevOps repository page that links users to the new GitHub location.
  5. The migration state is marked Migrated / Succeeded.

Monitor cutover progress

az devops migrations status --org https://dev.azure.com/<org>
                            --repository-id <repo-guid>

Wait until the migration shows status: Succeeded and stage: Migrated.

Note

ELM jobs run every 30 to 60 minutes. If you schedule cutover as soon as the migration enters the cutover stage, it might take up to 60 minutes before the cutover job starts.

Important

After cutover completes, pull requests opened in GitHub aren't synced back to Azure DevOps.

Review for cutover

If unresolved failures remain when the scheduled cutover time arrives, ELM moves the migration to ReviewForCutover instead of continuing automatically. For example, this condition can happen when some pull requests can't be migrated. In this state, you must review the failures and explicitly decide whether to proceed.

Review cutover failures

az devops migrations cutover review --org https://dev.azure.com/<org>
                                    --repository-id <repo-guid>

The command returns a summary of unresolved items:

Field Description
failedCount Number of items that failed to migrate.
blockedCount Number of items blocked by dependencies.
pendingCount Number of items still pending.
totalUnprocessedCount Total items requiring approval.
failedItems Detailed list of unprocessed items with state, type, and pull-request URL.

Review the failedItems list carefully so you understand which items aren't migrated if you choose to continue.

Options in ReviewForCutover

After you review the failures, choose one of the following options:

Option What it does When to use
Approve and proceed Accepts the failures and advances to cutover. You've reviewed all failures and are OK proceeding without those items.
Clear cutover date Resets to Synchronization. Migration keeps syncing. You want to fix the issues first and schedule a new cutover later.
Reschedule cutover Resets to Synchronization with a new cutover date. Run az devops migrations cutover set --date <new> again to set a new date. If failures resolve by the new date, cutover proceeds automatically. You want more time.
Delete the migration Deletes the migration record. An audit event is written; the source Azure DevOps repository is unchanged. You want to abandon this migration entirely.
Pause the migration Suspends syncing until you manually resume it. You need to pause all activity while you investigate.

Approve cutover

If you decide to continue, approve the cutover by accepting the number of items to skip:

az devops migrations cutover approve --org https://dev.azure.com/<org>
                                     --repository-id <repo-guid>
                                     --accept-failures <N>

Set <N> to a value greater than or equal to totalUnprocessedCount from the cutover review.

Warning

Approval is irreversible. There's no API to revoke an approval. If you approve by mistake, the only recovery path is az devops migrations abandon followed by recreating the migration.

Note

If new failures appear after you review and before you approve, the command is rejected with an HTTP 400 surfaced as a CLIError indicating the failure count no longer matches. Run cutover review again, note the updated totalUnprocessedCount, and retry the approval. Scripts and automation can match on the non-zero exit code.

After approval, the migration moves to ReadyForCutover:

  • If a cutover date is already scheduled, cutover proceeds automatically at the scheduled time.
  • If no cutover date is set, schedule one to proceed.

Next step

Complete post-migration tasks

Related content

  • Last updated on