ELM migrations: pipelines rewiring + cutover review/approve + TSG doc

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

@@ -42,6 +42,7 @@ def transform_cutover_review_table_output(result):
     blocked_count = result.get('blockedCount')
     pending_count = result.get('pendingCount')
     total_unprocessed = result.get('totalUnprocessedCount')
+    requires_pipeline_ack = result.get('requiresPipelineVerificationAcknowledgment')
     failed_items = result.get('failedItems') if isinstance(result.get('failedItems'), list) else []
 
     if not failed_items:
@@ -50,6 +51,7 @@ def transform_cutover_review_table_output(result):
         row['BlockedCount'] = blocked_count
         row['PendingCount'] = pending_count
         row['TotalUnprocessedCount'] = total_unprocessed
+        row['RequiresPipelineVerification'] = requires_pipeline_ack
         row['State'] = None
         row['Type'] = None
         row['PullRequestUrl'] = None
@@ -62,6 +64,7 @@ def transform_cutover_review_table_output(result):
         row['BlockedCount'] = blocked_count if index == 0 else None
         row['PendingCount'] = pending_count if index == 0 else None
         row['TotalUnprocessedCount'] = total_unprocessed if index == 0 else None
+        row['RequiresPipelineVerification'] = requires_pipeline_ack if index == 0 else None
         row['State'] = item.get('state') if isinstance(item, dict) else None
         row['Type'] = item.get('type') if isinstance(item, dict) else None
         row['PullRequestUrl'] = item.get('pullRequestUrl') if isinstance(item, dict) else None
@@ -70,6 +73,21 @@ def transform_cutover_review_table_output(result):
     return rows
 
 
+def transform_pipelines_list_table_output(result):
+    if not isinstance(result, dict):
+        return []
+    entries = result.get('pipelines') if isinstance(result.get('pipelines'), list) else []
+    return [_transform_pipeline_entry_row(entry) for entry in entries]
+
+
+def transform_pipeline_entries_table_output(result):
+    if isinstance(result, list):
+        return [_transform_pipeline_entry_row(entry) for entry in result]
+    if isinstance(result, dict) and isinstance(result.get('pipelines'), list):
+        return [_transform_pipeline_entry_row(entry) for entry in result.get('pipelines')]
+    return []
+
+
 def _unwrap_migration_list(result):
     if isinstance(result, dict) and 'value' in result:
         return result['value']
@@ -90,3 +108,16 @@ def _transform_migration_row(row):
     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
+
+
+def _transform_pipeline_entry_row(entry):
+    table_row = OrderedDict()
+    table_row['DefinitionId'] = entry.get('definitionId')
+    # Server may return name=null until pipeline-name hydration ships; fall back to yamlFilename
+    # so operators can still identify the row.
+    display_name = entry.get('name') or entry.get('yamlFilename')
+    table_row['Name'] = trim_for_display(display_name, _TARGET_TRUNCATION_LENGTH)
+    table_row['Classification'] = entry.get('classification')
+    table_row['Status'] = entry.get('status')
+    table_row['ErrorMessage'] = trim_for_display(entry.get('errorMessage'), _TARGET_TRUNCATION_LENGTH)
+    return table_row

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

@@ -16,13 +16,14 @@ def load_migration_help():
     helps['devops migrations list'] = """
     type: command
     short-summary: List migrations in an organization.
+    long-summary: 'By default the latest migration per repository is returned, regardless of state. Use --include-all to return the full migration history.'
     examples:
-      - name: List migrations.
+      - name: List the latest migration per repository.
         text: |
           az devops migrations list --org https://dev.azure.com/myorg
-      - name: List all migrations including inactive ones.
+      - name: List the full migration history for every repository.
         text: |
-          az devops migrations list --org https://dev.azure.com/myorg --include-inactive
+          az devops migrations list --org https://dev.azure.com/myorg --include-all
     """
 
     helps['devops migrations status'] = """
@@ -72,7 +73,8 @@ def load_migration_help():
 
     helps['devops migrations abandon'] = """
     type: command
-    short-summary: Abandon and delete a migration.
+    short-summary: Abandon a migration.
+    long-summary: '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.'
     examples:
       - name: Abandon and keep repository read-only (default).
         text: |
@@ -90,6 +92,7 @@ def load_migration_help():
     helps['devops migrations cutover review'] = """
     type: command
     short-summary: Review unprocessed migration items before cutover.
+    long-summary: 'The response includes requiresPipelineVerificationAcknowledgment. When true, cutover approve must be re-run with --pipelines-verified before the migration can proceed.'
     examples:
       - name: Review failures before approving cutover.
         text: |
@@ -98,11 +101,18 @@ def load_migration_help():
 
     helps['devops migrations cutover approve'] = """
     type: command
-    short-summary: Approve cutover by accepting a count of unprocessed items.
+    short-summary: Approve cutover by accepting unprocessed items and/or verifying rewired pipelines.
+    long-summary: 'Provide --accept-failures when cutover review surfaces unprocessed items, and/or --pipelines-verified when cutover review reports requiresPipelineVerificationAcknowledgment: true. At least one of the two must be supplied; both may be sent together in a single call.'
     examples:
       - name: Approve cutover after reviewing failures.
         text: |
           az devops migrations cutover approve --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --accept-failures 3
+      - name: Acknowledge pipeline verification only (no unprocessed items).
+        text: |
+          az devops migrations cutover approve --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --pipelines-verified
+      - name: Combine failure acceptance and pipeline verification in one call.
+        text: |
+          az devops migrations cutover approve --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --accept-failures 3 --pipelines-verified
     """
 
     helps['devops migrations cutover set'] = """
@@ -118,3 +128,53 @@ def load_migration_help():
     type: command
     short-summary: Cancel a scheduled cutover.
     """
+
+    helps['devops migrations pipelines'] = """
+    type: group
+    short-summary: Manage pipeline rewiring for migrations. (Preview)
+    """
+
+    helps['devops migrations pipelines list'] = """
+    type: command
+    short-summary: List pipeline rewiring configuration and per-pipeline status.
+    examples:
+      - name: List pipeline rewiring status.
+        text: |
+          az devops migrations pipelines list --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000
+    """
+
+    helps['devops migrations pipelines submit'] = """
+    type: command
+    short-summary: Submit pipelines for rewiring. (Preview)
+    examples:
+      - name: Submit pipelines with service connection and repository mappings.
+        text: |
+          az devops migrations pipelines submit --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --pipeline-ids 42 43 44 --service-connection-id 11111111-1111-1111-1111-111111111111 --repository-mapping aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa=myorg/shared-templates
+    """
+
+    helps['devops migrations pipelines update'] = """
+    type: command
+    short-summary: Bulk update pipeline rewiring configuration. (Preview)
+    examples:
+      - name: Add, remove, and update service connection.
+        text: |
+          az devops migrations pipelines update --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --add-ids 50 51 --remove-ids 42 --service-connection-id 22222222-2222-2222-2222-222222222222
+    """
+
+    helps['devops migrations pipelines retry'] = """
+    type: command
+    short-summary: Retry failed pipeline rewiring entries. (Preview)
+    examples:
+      - name: Retry specific failed pipelines.
+        text: |
+          az devops migrations pipelines retry --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --pipeline-ids 42 43
+    """
+
+    helps['devops migrations pipelines delete'] = """
+    type: command
+    short-summary: Delete pipeline rewiring data for a migration. (Preview)
+    examples:
+      - name: Delete rewiring config and cloned definitions.
+        text: |
+          az devops migrations pipelines delete --org https://dev.azure.com/myorg --repository-id 00000000-0000-0000-0000-000000000000 --migration-id 7 --yes
+    """

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

@@ -14,9 +14,52 @@ def load_migration_arguments(self, _):
         context.argument('repository_id', options_list='--repository-id',
                          help='ID of the Azure Repos repository (GUID).')
 
+    with self.argument_context('devops migrations pipelines') as context:
+        context.argument('repository_mapping', options_list='--repository-mapping', action='append',
+                         help='Repository mapping in the format <sourceRepoId>=<targetOwner>/<targetRepo>. '
+                              'Can be provided multiple times.')
+
+    with self.argument_context('devops migrations pipelines submit') as context:
+        context.argument('pipeline_ids', options_list='--pipeline-ids', nargs='+',
+                         help='Pipeline definition IDs. Accepts space-separated values '
+                              '(for example, 42 43 44) or comma-separated values '
+                              '(for example, 42,43,44).')
+        context.argument('service_connection_id', options_list='--service-connection-id',
+                         help='Project-scoped GitHub service connection ID (GUID). '
+                              'Optional if a connection was already attached via '
+                              'migrations create --pipeline-service-connection-id or '
+                              'pipelines update --service-connection-id.')
+
+    with self.argument_context('devops migrations pipelines update') as context:
+        context.argument('add_ids', options_list='--add-ids', nargs='+',
+                         help='Pipeline IDs to add. Accepts space-separated or comma-separated values.')
+        context.argument('remove_ids', options_list='--remove-ids', nargs='+',
+                         help='Pipeline IDs to remove. Accepts space-separated or comma-separated values.')
+        context.argument('retry_ids', options_list='--retry-ids', nargs='+',
+                         help='Failed pipeline IDs to retry. Accepts space-separated or comma-separated values.')
+        context.argument('service_connection_id', options_list='--service-connection-id',
+                         help='Project-scoped GitHub service connection ID (GUID).')
+
+    with self.argument_context('devops migrations pipelines retry') as context:
+        context.argument('pipeline_ids', options_list='--pipeline-ids', nargs='+',
+                         help='Pipeline definition IDs to retry. Accepts space-separated '
+                              'or comma-separated values.')
+
+    with self.argument_context('devops migrations pipelines delete') as context:
+        context.argument('migration_id', options_list='--migration-id', type=int,
+                         help='Migration ID used for pipeline rewiring cleanup.')
+        context.argument('yes', options_list=['--yes', '-y'], action='store_true',
+                         help='Do not prompt for confirmation.')
+
     with self.argument_context('devops migrations list') as context:
+        context.argument('include_all', options_list='--include-all', action='store_true',
+                         help='Return the full migration history (all records per repository). '
+                              'By default only the latest migration per repository is returned, '
+                              'regardless of its state.')
         context.argument('include_inactive', options_list='--include-inactive', action='store_true',
-                         help='Include inactive (completed, abandoned, failed) migrations in the results.')
+                         help='Deprecated. Use --include-all instead.',
+                         deprecate_info=context.deprecate(redirect='--include-all',
+                                                          target='--include-inactive', hide=False))
         context.argument('project', options_list='--project',
                          help='Optional project name or ID to filter migrations.')
 
@@ -27,9 +70,12 @@ def load_migration_arguments(self, _):
                          help='Target repository owner user ID. Deprecated and ignored when server-side '
                               'token-based owner resolution is enabled.')
         context.argument('github_token', options_list='--github-token',
-                         help='GitHub token used for migration authorization. Ignored when '
-                              '--service-endpoint-id is specified. If omitted, the CLI first '
-                              'checks ELM_GITHUB_TOKEN and then runs GitHub device flow.')
+                         help='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.')
         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',
@@ -40,12 +86,38 @@ def load_migration_arguments(self, _):
         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,MaxFileSize) or a non-negative '
-                              'integer bitmask.')
+                              'integer bitmask. Supported policy names (case-insensitive): None, '
+                              'ActivePullRequestCount, PullRequestDeltaSize, AgentPoolExists, MaxFileSize, '
+                              'MaxPullRequestSize, MaxPushPackSize, MaxReferenceNameLength, '
+                              'TargetRepositoryDoesNotExist, SourceRepositoryContainsLfsObjects, '
+                              'SourceRepositoryNotReadOnly, BoardsGitHubConnectionProvisioning, All.')
         context.argument('service_endpoint_id', options_list='--service-endpoint-id',
-                         help='Service endpoint ID (GUID) for the GitHub Enterprise Server connection. '
-                              'When specified, the server uses the service connection for GitHub '
-                              'authentication and the CLI skips GitHub device flow. Mutually exclusive '
-                              'with --github-token.')
+                         help='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.')
+        context.argument('enable_boards_github_connection',
+                         options_list='--enable-boards-github-connection', action='store_true',
+                         help='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.')
+        context.argument('enable_auto_discover_pipelines',
+                         options_list='--enable-auto-discover-pipelines', action='store_true',
+                         help='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.')
+        context.argument('pipeline_service_connection_id',
+                         options_list='--pipeline-service-connection-id',
+                         help='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).')
 
     with self.argument_context('devops migrations cutover set') as context:
         context.argument('cutover_date', options_list='--date',
@@ -56,6 +128,11 @@ def load_migration_arguments(self, _):
         context.argument('accept_failures', options_list='--accept-failures', type=int,
                          help='Number of unprocessed migration resources to accept before '
                               'proceeding with cutover.')
+        context.argument('pipelines_verified', options_list='--pipelines-verified', action='store_true',
+                         help='Acknowledge that all rewired pipelines have been verified. '
+                              'Required when "cutover review" returns '
+                              'requiresPipelineVerificationAcknowledgment: true. Can be combined '
+                              'with --accept-failures in a single approve call.')
 
     with self.argument_context('devops migrations resume') as context:
         context.argument('validate_only', options_list='--validate-only', action='store_true',