az devops migrations

  • Preview

Note

This reference is part of the azure-devops extension for the Azure CLI (version 2.30.0 or higher). The extension will automatically install the first time you run an az devops migrations command. Learn more about extensions.

This command group is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Manage enterprise live migrations.

This command group is a part of the azure-devops extension and is in preview. Availability may be limited (for example, to 1P/allowlisted users). For ELM migrations, --org should be your Azure DevOps organization URL (for example: https://dev.azure.com/myorg).

Commands

Name Description Type Status
az devops migrations abandon

Abandon a migration.

 Extension Preview
az devops migrations create

Create a migration for a repository.

 Extension Preview
az devops migrations cutover

Manage migration cutover.

 Extension Preview
az devops migrations cutover approve

Approve cutover by accepting unprocessed items and/or verifying rewired pipelines.

 Extension Preview
az devops migrations cutover cancel

Cancel a scheduled cutover.

 Extension Preview
az devops migrations cutover review

Review unprocessed migration items before cutover.

 Extension Preview
az devops migrations cutover set

Schedule cutover for a migration.

 Extension Preview
az devops migrations list

List migrations in an organization.

 Extension Preview
az devops migrations pause

Pause an active migration.

 Extension Preview
az devops migrations pipelines

Manage pipeline rewiring for migrations. (Preview).

 Extension Preview
az devops migrations pipelines delete

Delete pipeline rewiring data for a migration. (Preview).

 Extension Preview
az devops migrations pipelines list

List pipeline rewiring configuration and per-pipeline status.

 Extension Preview
az devops migrations pipelines retry

Retry failed pipeline rewiring entries. (Preview).

 Extension Preview
az devops migrations pipelines submit

Submit pipelines for rewiring. (Preview).

 Extension Preview
az devops migrations pipelines update

Bulk update pipeline rewiring configuration. (Preview).

 Extension Preview
az devops migrations resume

Resume a stopped (paused, failed) migration.

 Extension Preview
az devops migrations status

Get migration status for a repository.

 Extension Preview

az devops migrations abandon

Preview

Command group 'devops migrations' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Abandon a migration.

Moves the migration to an abandoned/failed state; the migration record is not purged. Pipeline rewiring data is left intact so a subsequent migration can reuse it.

az devops migrations abandon [--acquire-policy-token]
                             [--change-reference]
                             [--detect {false, true}]
                             [--org --organization]
                             [--remove-read-only]
                             [--repository-id]
                             [--yes]

Examples

Abandon and keep repository read-only (default).

az devops migrations abandon --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000

Abandon and set repository back to read-write.

az devops migrations abandon --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --remove-read-only

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--detect

Automatically detect organization.

Property Value
Accepted values: false, true
--org --organization

Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up via git config. Example: https://dev.azure.com/MyOrganizationName/.

--remove-read-only

Also set the Azure Repos repository back to read-write state by sending removeReadOnly=true.

Property Value
Default value: False
--repository-id

ID of the Azure Repos repository (GUID).

--yes -y

Do not prompt for confirmation.

Property Value
Default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az devops migrations create

Preview

Command group 'devops migrations' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Create a migration for a repository.

If --github-token is not provided, the CLI checks ELM_GITHUB_TOKEN and then runs GitHub device flow to acquire a token.

az devops migrations create [--acquire-policy-token]
                            [--agent-pool]
                            [--auto-discover --enable-auto-discover-pipelines]
                            [--change-reference]
                            [--cutover-date]
                            [--detect {false, true}]
                            [--enable-boards-gh --enable-boards-github-connection]
                            [--github-token]
                            [--org --organization]
                            [--pipeline-sc-id --pipeline-service-connection-id]
                            [--repository-id]
                            [--service-endpoint-id]
                            [--skip-validation]
                            [--target-owner-user-id]
                            [--target-repository]
                            [--validate-only]

Examples

Create a migration.

az devops migrations create --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --target-repository https://github.com/OrgName/RepoName --agent-pool <your-agent-pool>

Create a validate-only migration.

az devops migrations create --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --target-repository https://github.com/OrgName/RepoName --agent-pool <your-agent-pool> --validate-only --skip-validation ActivePullRequestCount,PullRequestDeltaSize

Create using a pre-generated GitHub token or PAT.

az devops migrations create --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --target-repository https://github.com/OrgName/RepoName --github-token <token>

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--agent-pool

Agent pool name to use for migration work.

--auto-discover --enable-auto-discover-pipelines

Opt in to automatic pipeline discovery at cutover. Off by default. When enabled, the ELM sync job walks the source repository and creates clone definitions for every pipeline that references it. Requires --pipeline-service-connection-id; without it discovery runs as a no-op and enrolls 0 pipelines. Pipeline rewiring itself is always available via az devops migrations pipelines submit / update.

Property Value
Default value: False
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--cutover-date

Scheduled cutover date/time (ISO 8601).

--detect

Automatically detect organization.

Property Value
Accepted values: false, true
--enable-boards-gh --enable-boards-github-connection

Opt in to provisioning the Azure Boards GitHub connection at cutover. Off by default. Requires the Azure Boards GitHub App to be installed on the target GitHub Enterprise organization before the migration runs.

Property Value
Default value: False
--github-token

GitHub user token used for user-identity verification on the target host. Independent of --service-endpoint-id. If omitted and --service-endpoint-id is not provided, the CLI checks ELM_GITHUB_TOKEN and then runs GitHub device flow. When --service-endpoint-id is provided, device flow is skipped; pass --github-token or set ELM_GITHUB_TOKEN to supply the user token.

--org --organization

Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up via git config. Example: https://dev.azure.com/MyOrganizationName/.

--pipeline-sc-id --pipeline-service-connection-id

Project-scoped GitHub service connection ID (GUID) attached at create time for pipeline rewiring. Required for full auto-discovery when combined with --enable-auto-discover-pipelines; optional in manual mode (pre-attaches the connection so subsequent pipelines submit calls only need --pipeline-ids).

--repository-id

ID of the Azure Repos repository (GUID).

--service-endpoint-id

Service endpoint ID (GUID) for the GitHub Enterprise Server connection used to sync commits to the target. Independent of user-identity verification: --github-token / ELM_GITHUB_TOKEN can be supplied alongside this flag. Device flow is skipped when this flag is set.

--skip-validation

Validation policies to skip. Accepts either a comma-separated list of policy names (for example, AgentPoolExists,MaxFileSize) or a non-negative integer bitmask. Supported policy names (case-insensitive): None, ActivePullRequestCount, PullRequestDeltaSize, AgentPoolExists, MaxFileSize, MaxPullRequestSize, MaxPushPackSize, MaxReferenceNameLength, TargetRepositoryDoesNotExist, SourceRepositoryContainsLfsObjects, SourceRepositoryNotReadOnly, BoardsGitHubConnectionProvisioning, All.

--target-owner-user-id

Target repository owner user ID. Deprecated and ignored when server-side token-based owner resolution is enabled.

--target-repository

Target repository URL (must start with http:// or https://).

--validate-only

Create in validate-only mode (pre-migration checks only).

Property Value
Default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az devops migrations list

Preview

Command group 'devops migrations' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

List migrations in an organization.

By default the latest migration per repository is returned, regardless of state. Use --include-all to return the full migration history.

az devops migrations list [--detect {false, true}]
                          [--include-all]
                          [--include-inactive]
                          [--org --organization]
                          [--project]

Examples

List the latest migration per repository.

az devops migrations list --org https://dev.azure.com/myorg

List the full migration history for every repository.

az devops migrations list --org https://dev.azure.com/myorg --include-all

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--detect

Automatically detect organization.

Property Value
Accepted values: false, true
--include-all

Return the full migration history (all records per repository). By default only the latest migration per repository is returned, regardless of its state.

Property Value
Default value: False
--include-inactive
Deprecated

Option '--include-inactive' has been deprecated and will be removed in a future release. Use '--include-all' instead.

Deprecated. Use --include-all instead.

Property Value
Default value: False
--org --organization

Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up via git config. Example: https://dev.azure.com/MyOrganizationName/.

--project

Optional project name or ID to filter migrations.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az devops migrations pause

Preview

Command group 'devops migrations' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Pause an active migration.

az devops migrations pause [--acquire-policy-token]
                           [--change-reference]
                           [--detect {false, true}]
                           [--org --organization]
                           [--repository-id]

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--detect

Automatically detect organization.

Property Value
Accepted values: false, true
--org --organization

Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up via git config. Example: https://dev.azure.com/MyOrganizationName/.

--repository-id

ID of the Azure Repos repository (GUID).

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az devops migrations resume

Preview

Command group 'devops migrations' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Resume a stopped (paused, failed) migration.

az devops migrations resume [--acquire-policy-token]
                            [--change-reference]
                            [--detect {false, true}]
                            [--migration]
                            [--org --organization]
                            [--repository-id]
                            [--validate-only]

Examples

Resume using the current mode.

az devops migrations resume --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000

Resume in validate-only mode.

az devops migrations resume --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --validate-only

Continue migration (clears validate-only mode).

az devops migrations resume --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --migration

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--detect

Automatically detect organization.

Property Value
Accepted values: false, true
--migration

Promote a succeeded validate-only migration to a full migration (sets validateOnly=false and statusRequested=active).

Property Value
Default value: False
--org --organization

Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up via git config. Example: https://dev.azure.com/MyOrganizationName/.

--repository-id

ID of the Azure Repos repository (GUID).

--validate-only

Resume in validate-only mode.

Property Value
Default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az devops migrations status

Preview

Command group 'devops migrations' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Get migration status for a repository.

az devops migrations status [--acquire-policy-token]
                            [--change-reference]
                            [--detect {false, true}]
                            [--org --organization]
                            [--repository-id]

Examples

Get migration status by repository id.

az devops migrations status --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--detect

Automatically detect organization.

Property Value
Accepted values: false, true
--org --organization

Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up via git config. Example: https://dev.azure.com/MyOrganizationName/.

--repository-id

ID of the Azure Repos repository (GUID).

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False