Add ELM migrations commands

Author: bhuvanshah7

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
@@ -48,7 +52,7 @@ 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'))):
+            kwargs['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/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') or row.get('repositoryID') or row.get('repository')
+    table_row['TargetRepository'] = trim_for_display(row.get('targetRepo') or row.get('targetRepository'),
+                                                     _TARGET_TRUNCATION_LENGTH)
+    table_row['State'] = row.get('state')
+    table_row['Stage'] = row.get('stage')
+    table_row['ValidateOnly'] = row.get('validateOnly')
+    table_row['CutoverDate'] = date_time_to_only_date(row.get('cutoverDate') or row.get('scheduledCutoverDate'))
+    table_row['CodeSyncDate'] = date_time_to_only_date(row.get('codeSyncDate'))
+    table_row['PrSyncDate'] = date_time_to_only_date(row.get('prSyncDate'))
+    return table_row

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

@@ -0,0 +1,94 @@
+# --------------------------------------------------------------------------------------------
+# 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.
+    """
+
+    helps['devops migrations list'] = """
+    type: command
+    short-summary: List migrations in an organization.
+    examples:
+      - name: List migrations.
+        text: |
+          az devops migrations list --org https://codedev.ms/elmo1
+    """
+
+    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://codedev.ms/elmo1 --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 validation-only migration.
+        text: |
+          az devops migrations create --org https://codedev.ms/elmo1 --repository-id 00000000-0000-0000-0000-000000000000 \
+            --target-repository https://microsoft.ghe.com/1ES/Gardener --target-owner-user-id GeoffCoxMSFT --validate-only
+    """
+
+    helps['devops migrations pause'] = """
+    type: command
+    short-summary: Pause an active migration.
+    """
+
+    helps['devops migrations resume'] = """
+    type: command
+    short-summary: Resume a paused migration.
+    """
+
+    helps['devops migrations abandon'] = """
+    type: command
+    short-summary: Abandon and delete a migration.
+    """
+
+    helps['devops migrations set-validate-only'] = """
+    type: command
+    short-summary: Set validate-only mode on or off.
+    examples:
+      - name: Turn validate-only on.
+        text: |
+          az devops migrations set-validate-only --org https://codedev.ms/elmo1 --repository-id 00000000-0000-0000-0000-000000000000 --on
+      - name: Turn validate-only off.
+        text: |
+          az devops migrations set-validate-only --org https://codedev.ms/elmo1 --repository-id 00000000-0000-0000-0000-000000000000 --off
+    """
+
+    helps['devops migrations migrate'] = """
+    type: command
+    short-summary: Start full migration after validation.
+    """
+
+    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://codedev.ms/elmo1 --repository-id 00000000-0000-0000-0000-000000000000 \
+            --scheduled-cutover-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,39 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from azure.cli.core.commands.parameters import get_three_state_flag
+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 repository (GUID).')
+
+    with self.argument_context('devops migrations create') as context:
+        context.argument('target_repository', options_list='--target-repository',
+                         help='Target GitHub repository URL. Example: https://microsoft.ghe.com/OrgName/RepoName')
+        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',
+                         help='Validate only (true/false). Defaults to true.',
+                         arg_type=get_three_state_flag())
+        context.argument('scheduled_cutover_date', options_list='--scheduled-cutover-date',
+                         type=convert_date_string_to_iso8601,
+                         help='Scheduled cutover date/time (ISO 8601).')
+
+    with self.argument_context('devops migrations cutover set') as context:
+        context.argument('scheduled_cutover_date', options_list='--scheduled-cutover-date',
+                         type=convert_date_string_to_iso8601,
+                         help='Scheduled cutover date/time (ISO 8601).')
+
+    with self.argument_context('devops migrations set-validate-only') as context:
+        context.argument('on', options_list='--on', action='store_true',
+                         help='Set validate-only to true.')
+        context.argument('off', options_list='--off', action='store_true',
+                         help='Set validate-only to false.')

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

@@ -0,0 +1,31 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from azure.cli.core.commands import CliCommandType
+from azext_devops.dev.common.exception_handler import azure_devops_exception_handler
+from ._format import transform_migrations_table_output, transform_migration_table_output
+
+
+migrationOps = CliCommandType(
+    operations_tmpl='azext_devops.dev.migration.migration#{}',
+    exception_handler=azure_devops_exception_handler
+)
+
+
+def load_migration_commands(self, _):
+    with self.command_group('devops migrations', command_type=migrationOps) as g:
+        g.command('list', 'list_migrations', table_transformer=transform_migrations_table_output)
+        g.command('status', 'get_migration', table_transformer=transform_migration_table_output)
+        g.command('create', 'create_migration', table_transformer=transform_migration_table_output)
+        g.command('pause', 'pause_migration', table_transformer=transform_migration_table_output)
+        g.command('resume', 'resume_migration', table_transformer=transform_migration_table_output)
+        g.command('set-validate-only', 'set_validate_only', table_transformer=transform_migration_table_output)
+        g.command('migrate', 'migrate_migration', table_transformer=transform_migration_table_output)
+        g.command('abandon', 'delete_migration',
+                  confirmation='Are you sure you want to abandon this migration?')
+
+    with self.command_group('devops migrations cutover', command_type=migrationOps) as g:
+        g.command('set', 'schedule_cutover', table_transformer=transform_migration_table_output)
+        g.command('cancel', 'cancel_cutover', table_transformer=transform_migration_table_output)