Improve migrations CLI UX validations and guidance

Author: bhuvanshah7

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

@@ -12,15 +12,15 @@ 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).')
+                         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.')
 
     with self.argument_context('devops migrations create') as context:
         context.argument('target_repository', options_list='--target-repository',
-                         help='Target repository URL.')
+                         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',
@@ -42,4 +42,5 @@ def load_migration_arguments(self, _):
         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='Continue the migration (clears any validate-only mode).')
+                         help='Promote a succeeded validate-only migration to a full migration '
+                              '(sets validateOnly=false and statusRequested=active).')

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

@@ -3,6 +3,8 @@
 # Licensed under the MIT License. See License.txt in the project root for license information.
 # --------------------------------------------------------------------------------------------
 
+import re
+
 from msrest import Configuration
 from msrest.service_client import ServiceClient
 from msrest.universal_http import ClientRequest
@@ -26,6 +28,9 @@
     'synchronization',
     'cutover'
 }
+_URL_PATTERN = re.compile(r'^https?://[^\s]+$', re.IGNORECASE)
+
+
 def list_migrations(include_inactive=False, organization=None, detect=None):
     organization = _resolve_org_for_auth(organization, detect)
     client = _get_service_client(organization)
@@ -53,7 +58,14 @@ def get_migration(repository_id=None, organization=None, detect=None):
 def create_migration(repository_id=None, target_repository=None, target_owner_user_id=None,
                      validate_only=False, cutover_date=None, agent_pool=None,
                      skip_validation=None, organization=None, detect=None):
+    target_repository = _normalize_optional_text(target_repository)
+    target_owner_user_id = _normalize_optional_text(target_owner_user_id)
     agent_pool = _normalize_optional_text(agent_pool)
+
+    if not target_repository:
+        raise CLIError('--target-repository must be specified.')
+    if not _URL_PATTERN.match(target_repository):
+        raise CLIError('--target-repository must be a valid URL starting with http:// or https://.')
     if not target_owner_user_id:
         raise CLIError('--target-owner-user-id must be specified.')
 
@@ -92,19 +104,22 @@ def resume_migration(repository_id=None, validate_only=False, migration=False, o
         return _promote_to_full_migration(migration_data, repository_id, organization)
 
     if _is_migration_active(migration_data):
-        status = migration_data.get('statusRequested') or migration_data.get('status')
-        stage = migration_data.get('stage')
-        raise CLIError('Migration is active (statusRequested: {}, stage: {}). Pause it before resuming or changing mode.'
-                       .format(status, stage))
+        state_text = _get_migration_state_text(migration_data)
+        raise CLIError('Migration is currently active ({}). Pause it first using '
+                       '"az devops migrations pause --repository-id <guid>" before resuming or changing mode.'
+                       .format(state_text))
 
     if _is_migration_terminal(migration_data):
         status = _normalize_state(migration_data.get('status'))
         is_val_only = migration_data.get('validateOnly') is True
         if status == 'succeeded' and is_val_only:
-            raise CLIError('Validation already succeeded. Use --migration to promote to a full migration, '
-                           'or abandon and create a new one.')
+            raise CLIError('Validation already succeeded. Promote it with '
+                           '"az devops migrations resume --repository-id <guid> --migration", '
+                           'or abandon and create a new migration.')
         if status == 'succeeded':
-            raise CLIError('Migration already succeeded. Use abandon to reset, then create a new migration.')
+            raise CLIError('Migration already succeeded. Use '
+                           '"az devops migrations abandon --repository-id <guid>" to reset, '
+                           'then create a new migration.')
 
     validate_only_value = None
     if validate_only:
@@ -168,6 +183,22 @@ def _normalize_state(value):
     return normalized.replace(' ', '').replace('-', '').replace('_', '')
 
 
+def _get_migration_state_text(migration):
+    status_requested = migration.get('statusRequested')
+    status = migration.get('status')
+    stage = migration.get('stage')
+
+    parts = []
+    if status_requested:
+        parts.append('statusRequested: {}'.format(status_requested))
+    if status:
+        parts.append('status: {}'.format(status))
+    if stage:
+        parts.append('stage: {}'.format(stage))
+
+    return ', '.join(parts) if parts else 'state unknown'
+
+
 def _is_migration_active(migration):
     if not isinstance(migration, dict):
         return False

azure-devops/azext_devops/tests/latest/migration/test_migration.py

@@ -72,6 +72,29 @@ def test_create_migration_payload_defaults_validate_only_false(self):
             payload = mock_send.call_args[0][3]
             self.assertFalse(payload['validateOnly'])
 
+    def test_create_migration_fails_without_target_repository(self):
+        with self.assertRaises(CLIError) as ctx:
+            create_migration(
+                repository_id='00000000-0000-0000-0000-000000000000',
+                target_owner_user_id='GeoffCoxMSFT',
+                agent_pool='MigrationPool',
+                organization=self._TEST_ORG,
+                detect=False
+            )
+        self.assertIn('--target-repository must be specified', str(ctx.exception))
+
+    def test_create_migration_fails_with_invalid_target_repository_url(self):
+        with self.assertRaises(CLIError) as ctx:
+            create_migration(
+                repository_id='00000000-0000-0000-0000-000000000000',
+                target_repository='ghe.example.com/OrgName/RepoName',
+                target_owner_user_id='GeoffCoxMSFT',
+                agent_pool='MigrationPool',
+                organization=self._TEST_ORG,
+                detect=False
+            )
+        self.assertIn('must be a valid URL', str(ctx.exception))
+
     def test_create_migration_without_agent_pool(self):
         with patch('azext_devops.dev.migration.migration.resolve_instance') as mock_resolve, \
              patch('azext_devops.dev.migration.migration._get_service_client') as mock_client, \
@@ -261,19 +284,21 @@ def test_resume_fails_when_active(self):
             mock_get.return_value = {'status': 'active', 'stage': 'synchronization'}
             mock_resolve.return_value = self._TEST_ORG
 
-            with self.assertRaises(CLIError):
+            with self.assertRaises(CLIError) as ctx:
                 resume_migration(repository_id='00000000-0000-0000-0000-000000000000',
                                  organization=self._TEST_ORG, detect=False)
+            self.assertIn('az devops migrations pause', str(ctx.exception))
 
     def test_resume_fails_when_active_via_statusRequested(self):
         with patch('azext_devops.dev.migration.migration.get_migration') as mock_get, \
              patch('azext_devops.dev.migration.migration.resolve_instance') as mock_resolve:
             mock_get.return_value = {'statusRequested': 'Active', 'stage': 'validation'}
             mock_resolve.return_value = self._TEST_ORG
 
-            with self.assertRaises(CLIError):
+            with self.assertRaises(CLIError) as ctx:
                 resume_migration(repository_id='00000000-0000-0000-0000-000000000000',
                                  organization=self._TEST_ORG, detect=False)
+            self.assertIn('statusRequested: Active', str(ctx.exception))
 
     def test_resume_sets_validate_only(self):
         with patch('azext_devops.dev.migration.migration.get_migration') as mock_get, \

doc/migrations.md

@@ -6,16 +6,28 @@ The `az devops migrations` command group manages enterprise live migrations for
 
 - Azure DevOps CLI with the Azure DevOps extension installed.
 - Sign in using `az login` or `az devops login`.
-- Use `--org` to specify your Azure DevOps org URL (e.g., `https://dev.azure.com/myorg`).
+- Configure a default org once to avoid repeating `--org`:
+
+```bash
+az devops configure --defaults organization=https://dev.azure.com/myorg
+```
+
+- You can still override per command with `--org`.
 
 ## Required inputs
 
 - `--repository-id` is the Azure Repos repository GUID.
 - `--target-repository` is the target repository URL.
 - `--target-owner-user-id` is required for create.
-- `--agent-pool` is required for create.
+- `--agent-pool` is optional for create.
 - `--cutover-date` / `--date` must be ISO 8601, for example: `2030-12-31T11:59:00Z`.
 
+### How to find `--repository-id`
+
+```bash
+az repos show --repository MyRepo --project MyProject --query id -o tsv
+```
+
 ## Command reference
 
 - `list`: List migrations for the org. Use `--include-inactive` to include completed/failed/suspended migrations.
@@ -24,11 +36,20 @@ The `az devops migrations` command group manages enterprise live migrations for
 - `pause`: Pause an active migration.
 - `resume`: Resume a stopped (paused, failed) migration. Optional flags:
   - `--validate-only`: Resume in validate-only mode.
-  - `--migration`: Continue the migration (clears validate-only mode).
+  - `--migration`: Promote a succeeded validate-only migration to full migration.
+    This updates the existing migration by setting `validateOnly=false` and `statusRequested=active`.
   If a migration is active, pause it before resuming.
 - `cutover set` / `cutover cancel`: Schedule or cancel cutover.
 - `abandon`: Abandon and delete a migration.
 
+## Status fields
+
+- `statusRequested`: Desired state requested by client.
+- `status`: Current overall status reported by service.
+- `stage`: Current active stage (for example, validation, synchronization, cutover).
+
+If a command is blocked, inspect all three fields from `status` output to understand whether the migration is active, terminal, or promotable.
+
 ## Common workflows
 
 ### List migrations
@@ -87,6 +108,17 @@ az devops migrations resume --org https://dev.azure.com/myorg \
   --repository-id 00000000-0000-0000-0000-000000000000 --migration
 ```
 
+### Promote a succeeded validate-only migration
+
+After validation succeeds, run:
+
+```bash
+az devops migrations resume --org https://dev.azure.com/myorg \
+  --repository-id 00000000-0000-0000-0000-000000000000 --migration
+```
+
+This promotes the same migration record (no new migration is created).
+
 ### Schedule or cancel cutover
 
 ```bash
@@ -104,3 +136,19 @@ az devops migrations cutover cancel --org https://dev.azure.com/myorg \
 az devops migrations abandon --org https://dev.azure.com/myorg \
   --repository-id 00000000-0000-0000-0000-000000000000
 ```
+
+## Troubleshooting
+
+- Error: migration is active.
+  Pause first, then retry resume or mode changes.
+
+```bash
+az devops migrations pause --org https://dev.azure.com/myorg \
+  --repository-id 00000000-0000-0000-0000-000000000000
+```
+
+- Error: validation already succeeded.
+  Use `resume --migration` to promote instead of re-running validate-only.
+
+- Error: `--target-repository` must be valid.
+  Ensure it is a fully qualified URL starting with `http://` or `https://`.