Add ELM migrations commands (#1481)

* Add ELM migrations commands

* Add migration create options

* Fix style checks

* Use org base for ELM migrations

* Adjust BuildWheel task for Windows paths

* Allow GitHub.com targets and fix help YAML

* Simplify migration resume flow

* Add migrations command reference

* Fix BuildWheel task on Windows

* Fix markdown lint spacing

* Fix markdown lint and flake8 indentation errors

* Add --include-inactive help example and unit test for list migrations

* Fix convert_date_string_to_iso8601 returning datetime instead of string for tz-aware inputs

* Apply dev feedback: remove URL validation, fix validate-only default, unify flag naming, generic skip-validation help

* Update ELM migrations TSG with current params, codedev.ms troubleshooting, output formats

* TSG: add complete command/param reference, list step, cutover cancel, all optional params

* TSG: restructure as end-to-end guide with setup, lifecycle, walkthrough, and scenarios

* TSG: add fresh-user onboarding, concrete examples, status interpretation table, shell note

* docs: update TSG to use ADO org URL instead of separate ELM service URL

* docs: update migrations.md to use ADO org URL instead of ELM service URL

* Fix statusRequested field handling in pause/resume and update help URLs

* Make --agent-pool optional; server assigns default pool

- Remove required check for --agent-pool in create_migration
- Conditionally include agentPoolName in payload only when provided
- Server auto-assigns EnterpriseLiveMigrationPool when omitted
- Update tests: replace required-agent-pool tests with optional behavior tests

* Update migration changes and tests

* Promote validate-only migrations via PUT state update

* Improve migrations CLI UX validations and guidance

* Expand ELM migration docs and TSG guidance

* Support skip-validation names and integer values

* Add project filter support for migrations list

* Fix flake8 W503 in migration state check

* Fix markdown lint spacing and list formatting

* Fix remaining markdown lint issues in migration docs

* Fix Run_Style_Check missing dependency on Build_Publish_Azure_CLI_Test_SDK

---------

Co-authored-by: Bhuvan Shah <bhuvanshah@microsoft.com>

Author: bhuvanshahMSFT

.flake8

@@ -21,5 +21,8 @@ exclude =
     scripts
     doc
     build_scripts
+    env
+    venv
+    .venv
 	*/test/*
     */devops_sdk/*

.github/workflows/pr-workflow.yml

@@ -140,6 +140,7 @@ jobs:
           path: ${{ github.workspace }}/azure-devops/htmlcov
 
   Run_Style_Check:
+    needs: Build_Publish_Azure_CLI_Test_SDK
     runs-on: macOS-latest
     steps:
       - uses: actions/checkout@v4

.vscode/tasks.json

@@ -3,15 +3,18 @@
     "tasks": [
       {
         "label": "BuildWheel",
-        "command": "${command:python.interpreterPath}",
+        "type": "shell",
+        "command": "python",
         "args": [
           "setup.py",
           "sdist",
           "bdist_wheel"
         ],
-        "type": "shell",
         "options": {
-          "cwd": "${workspaceRoot}/azure-devops/"
+          "cwd": "${workspaceRoot}/azure-devops/",
+          "env": {
+            "PATH": "${workspaceRoot}\\env\\Scripts;${env:PATH}"
+          }
         },
         "presentation": {
             "echo": true,

README.md

@@ -28,6 +28,7 @@ $az [group] [subgroup] [command] {parameters}
 ```
 
 Adding the Azure DevOps Extension adds `devops`, `pipelines`, `artifacts`, `boards` and `repos` groups.
+Enterprise live migrations are available under `az devops migrations`.
 For usage and help content for any command, pass in the -h parameter, for example:
 
 ```bash
@@ -43,6 +44,7 @@ Group
 
 Subgroups:
     admin            : Manage administration operations.
+    migrations       : Manage enterprise live migrations.
     extension        : Manage extensions.
     project          : Manage team projects.
     security         : Manage security related operations.
@@ -64,6 +66,7 @@ Commands:
 - Checkout the CLI docs at [docs.microsoft.com - Azure DevOps CLI](https://docs.microsoft.com/azure/devops/cli/).
 - Check out other examples in the [How-to guides](https://docs.microsoft.com/azure/devops/cli/?view=azure-devops#how-to-guides) section.
 - You can view the various commands and its usage here - [docs.microsoft.com - Azure DevOps Extension Reference](https://docs.microsoft.com/en-us/cli/azure/devops?view=azure-cli-latest)
+- Enterprise live migrations guide: [doc/migrations.md](doc/migrations.md)
 
 ## Contribute
 

azure-devops/azext_devops/__init__.py

@@ -21,6 +21,8 @@ def load_command_table(self, args):
         load_admin_commands(self, args)
         from azext_devops.dev.boards.commands import load_work_commands
         load_work_commands(self, args)
+        from azext_devops.dev.migration.commands import load_migration_commands
+        load_migration_commands(self, args)
         from azext_devops.dev.pipelines.commands import load_build_commands
         load_build_commands(self, args)
         from azext_devops.dev.repos.commands import load_code_commands
@@ -36,6 +38,8 @@ def load_arguments(self, command):
         load_admin_arguments(self, command)
         from azext_devops.dev.boards.arguments import load_work_arguments
         load_work_arguments(self, command)
+        from azext_devops.dev.migration.arguments import load_migration_arguments
+        load_migration_arguments(self, command)
         from azext_devops.dev.pipelines.arguments import load_build_arguments
         load_build_arguments(self, command)
         from azext_devops.dev.repos.arguments import load_code_arguments
@@ -47,8 +51,8 @@ def load_arguments(self, command):
 
     @staticmethod
     def post_parse_args(_cli_ctx, **kwargs):
-        if (kwargs.get('command', None) and
-                kwargs['command'].startswith(('devops', 'boards', 'artifacts', 'pipelines', 'repos'))):
+        command = kwargs.get('command', None)
+        if command and command.startswith(('devops', 'boards', 'artifacts', 'pipelines', 'repos', 'migrations')):
             from azext_devops.dev.common.telemetry import set_tracking_data
             # we need to set tracking data only after we know that all args are valid,
             # otherwise we may log EUII data that a user inadvertently sent as an argument

azure-devops/azext_devops/dev/common/arguments.py

@@ -25,8 +25,7 @@ def convert_date_string_to_iso8601(value, argument=None):
     if d.tzinfo is None:
         from dateutil.tz import tzlocal
         d = d.replace(tzinfo=tzlocal())
-        d = d.isoformat()
-    return d
+    return d.isoformat()
 
 
 def convert_date_only_string_to_iso8601(value, argument=None):

azure-devops/azext_devops/dev/migration/__init__.py

@@ -0,0 +1,8 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from ._help import load_migration_help
+
+load_migration_help()

azure-devops/azext_devops/dev/migration/_format.py

@@ -0,0 +1,46 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from collections import OrderedDict
+from azext_devops.dev.common.format import trim_for_display, date_time_to_only_date
+
+
+_TARGET_TRUNCATION_LENGTH = 60
+
+
+def transform_migrations_table_output(result):
+    migrations = _unwrap_migration_list(result)
+    table_output = []
+    for item in migrations:
+        table_output.append(_transform_migration_row(item))
+    return table_output
+
+
+def transform_migration_table_output(result):
+    if result is None:
+        return []
+    return [_transform_migration_row(result)]
+
+
+def _unwrap_migration_list(result):
+    if isinstance(result, dict) and 'value' in result:
+        return result['value']
+    if isinstance(result, list):
+        return result
+    return []
+
+
+def _transform_migration_row(row):
+    table_row = OrderedDict()
+    table_row['RepositoryId'] = row.get('repositoryId')
+    table_row['TargetRepository'] = trim_for_display(row.get('targetRepository'),
+                                                     _TARGET_TRUNCATION_LENGTH)
+    table_row['Status'] = row.get('status')
+    table_row['Stage'] = row.get('stage')
+    table_row['ValidateOnly'] = row.get('validateOnly')
+    table_row['CutoverDate'] = date_time_to_only_date(row.get('scheduledCutoverDate'))
+    table_row['CodeSyncDate'] = date_time_to_only_date(row.get('codeSyncDate'))
+    table_row['PrSyncDate'] = date_time_to_only_date(row.get('pullRequestSyncDate'))
+    return table_row

azure-devops/azext_devops/dev/migration/_help.py

@@ -0,0 +1,91 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from knack.help_files import helps
+
+
+def load_migration_help():
+    helps['devops migrations'] = """
+    type: group
+    short-summary: Manage enterprise live migrations.
+    long-summary: 'This command group is a part of the azure-devops extension. For ELM migrations, --org should be your Azure DevOps organization URL (for example: https://dev.azure.com/myorg).'
+    """
+
+    helps['devops migrations list'] = """
+    type: command
+    short-summary: List migrations in an organization.
+    examples:
+      - name: List migrations.
+        text: |
+          az devops migrations list --org https://dev.azure.com/myorg
+      - name: List all migrations including inactive ones.
+        text: |
+          az devops migrations list --org https://dev.azure.com/myorg --include-inactive
+    """
+
+    helps['devops migrations status'] = """
+    type: command
+    short-summary: Get migration status for a repository.
+    examples:
+      - name: Get migration status by repository id.
+        text: |
+          az devops migrations status --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000
+    """
+
+    helps['devops migrations create'] = """
+    type: command
+    short-summary: Create a migration for a repository.
+    examples:
+      - name: Create a migration.
+        text: |
+          az devops migrations create --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --target-repository https://github.com/OrgName/RepoName --target-owner-user-id OwnerUserId --agent-pool MigrationPool
+      - name: Create a validate-only migration.
+        text: |
+          az devops migrations create --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --target-repository https://github.com/OrgName/RepoName --target-owner-user-id OwnerUserId --agent-pool MigrationPool --validate-only --skip-validation ActivePullRequestCount,PullRequestDeltaSize
+    """
+
+    helps['devops migrations pause'] = """
+    type: command
+    short-summary: Pause an active migration.
+    """
+
+    helps['devops migrations resume'] = """
+    type: command
+    short-summary: Resume a stopped (paused, failed) migration.
+    examples:
+      - name: Resume using the current mode.
+        text: |
+          az devops migrations resume --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000
+      - name: Resume in validate-only mode.
+        text: |
+          az devops migrations resume --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --validate-only
+      - name: Continue migration (clears validate-only mode).
+        text: |
+          az devops migrations resume --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --migration
+    """
+
+    helps['devops migrations abandon'] = """
+    type: command
+    short-summary: Abandon and delete a migration.
+    """
+
+    helps['devops migrations cutover'] = """
+    type: group
+    short-summary: Manage migration cutover.
+    """
+
+    helps['devops migrations cutover set'] = """
+    type: command
+    short-summary: Schedule cutover for a migration.
+    examples:
+      - name: Schedule cutover.
+        text: |
+          az devops migrations cutover set --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --date 2030-12-31T11:59:00Z
+    """
+
+    helps['devops migrations cutover cancel'] = """
+    type: command
+    short-summary: Cancel a scheduled cutover.
+    """

azure-devops/azext_devops/dev/migration/arguments.py

@@ -0,0 +1,50 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from azext_devops.dev.common.arguments import convert_date_string_to_iso8601
+from azext_devops.dev.team.arguments import load_global_args
+
+
+# pylint: disable=too-many-statements
+def load_migration_arguments(self, _):
+    with self.argument_context('devops migrations') as context:
+        load_global_args(context)
+        context.argument('repository_id', options_list='--repository-id',
+                         help='ID of the Azure Repos repository (GUID).')
+
+    with self.argument_context('devops migrations list') as context:
+        context.argument('include_inactive', options_list='--include-inactive', action='store_true',
+                         help='Include inactive (completed, abandoned, failed) migrations in the results.')
+        context.argument('project', options_list='--project',
+                         help='Optional project name or ID to filter migrations.')
+
+    with self.argument_context('devops migrations create') as context:
+        context.argument('target_repository', options_list='--target-repository',
+                         help='Target repository URL (must start with http:// or https://).')
+        context.argument('target_owner_user_id', options_list='--target-owner-user-id',
+                         help='Target repository owner user ID.')
+        context.argument('validate_only', options_list='--validate-only', action='store_true',
+                         help='Create in validate-only mode (pre-migration checks only).')
+        context.argument('cutover_date', options_list='--cutover-date',
+                         type=convert_date_string_to_iso8601,
+                         help='Scheduled cutover date/time (ISO 8601).')
+        context.argument('agent_pool', options_list='--agent-pool',
+                         help='Agent pool name to use for migration work.')
+        context.argument('skip_validation', options_list='--skip-validation',
+                         help='Validation policies to skip. Accepts either a comma-separated list of '
+                              'policy names (for example, AgentPoolExists,MaxRepoSize) or a non-negative '
+                              'integer bitmask.')
+
+    with self.argument_context('devops migrations cutover set') as context:
+        context.argument('cutover_date', options_list='--date',
+                         type=convert_date_string_to_iso8601,
+                         help='The date and time for cutover (ISO 8601).')
+
+    with self.argument_context('devops migrations resume') as context:
+        context.argument('validate_only', options_list='--validate-only', action='store_true',
+                         help='Resume in validate-only mode.')
+        context.argument('migration', options_list='--migration', action='store_true',
+                         help='Promote a succeeded validate-only migration to a full migration '
+                              '(sets validateOnly=false and statusRequested=active).')