[Migrate] Add az migrate runbook command group for wave runbooks

[krdhruva]

🤖 PR Validation — ⚠️ Review suggested

Breaking Changes
⚠️ None

⚠️Azure CLI Extensions Breaking Change Test

⚠️migrate

rule	cmd_name	rule_message	suggest_message
⚠️ 1010 - ParaPropUpdate	migrate get-discovered-server	cmd migrate get-discovered-server update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1010 - ParaPropUpdate	migrate local replication get	cmd migrate local replication get update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1010 - ParaPropUpdate	migrate local replication get-job	cmd migrate local replication get-job update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1010 - ParaPropUpdate	migrate local replication init	cmd migrate local replication init update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1010 - ParaPropUpdate	migrate local replication new	cmd migrate local replication new update parameter project_name: updated property options from ['--project-name'] to ['--project-name', '-p']
⚠️ 1011 - SubgroupAdd	migrate runbook	sub group migrate runbook added

---

This checklist is used to make sure that common guidelines for a pull request are followed.
Related command
az migrate runbook

Adds the az migrate runbook command surface for Azure Migrate wave runbooks:

• runbook (generate, show, list, update, regenerate, delete, wait)
• runbook definition (show, download, visualize) and definition step (add, update, remove) / definition workstream (split, merge)
• runbook parameter and runbook execution parameter (download, upload)
• runbook execution (start, show, list, pause, resume, cancel, visualize) and execution step (retry, approve, complete)

Version bumped to 3.0.0b6; HISTORY.rst updated.

General Guidelines

• Have you run azdev style <YOUR_EXT> locally? (pip install azdev required)
• Have you run python scripts/ci/test_index.py -q locally? (pip install azdev required)
• My extension version conforms to the Extension version schema

For new extensions:

• My extension description/summary conforms to the Extension Summary Guidelines.

About Extension Publish

There is a pipeline to automatically build, upload and publish extension wheels.
Once your pull request is merged into main branch, a new pull request will be created to update src/index.json automatically.
You only need to update the version information in file setup.py and historical information in file HISTORY.rst in your PR but do not modify src/index.json.

[azure-client-tools-bot-prd]

Hi krdhruva,
Please write the description of changes which can be perceived by customers into HISTORY.rst.
If you want to release a new extension version, please update the version in pyproject.toml (or setup.py, if the extension has not migrated yet) as well.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Aditya Pujara (a0x1ab)]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 pipeline(s).

[Copilot]

Pull request overview

Adds a new az migrate runbook command group to the migrate extension, including runbook CRUD, definition/step/workstream management, execution lifecycle + step actions, artifact (SAS ZIP) download/upload flows, and offline HTML visualization. This extends the existing migrate extension architecture with shared ARM and artifact helpers, plus scenario/unit tests and versioning updates.

Changes:

• Introduce migrate runbook CLI surface (runbook, definition, steps/workstreams, parameters, executions) backed by a shared ArmClient and artifact ZIP helpers.
• Add offline visualization pipeline (DAG + grid view models, HTML template, renderer) for definitions and execution status.
• Add tests/recordings, update linter exclusions, bump extension version to 3.0.0b6, and update release history.

Reviewed changes

Copilot reviewed 70 out of 70 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/migrate/spec/Runbooks/UpdateRunbookStep.yml	New REST example for updating a definition step.
src/migrate/spec/Runbooks/SplitRunbookWorkstream.yml	New REST example for splitting a workstream.
src/migrate/spec/Runbooks/runbookput.json	New JSON sample payload for runbook create.
src/migrate/spec/Runbooks/RegenerateRunbook.yml	New REST example for regenerate operation.
src/migrate/spec/Runbooks/MergeRunbookWorkstreams.yml	New REST example for merging workstreams.
src/migrate/spec/Runbooks/ListRunbooks.yml	New REST example for listing runbooks.
src/migrate/spec/Runbooks/GetRunbook.yml	New REST example for showing a runbook.
src/migrate/spec/Runbooks/GenerateDownloadUrl.yml	New REST example for generating artifact download URL.
src/migrate/spec/Runbooks/DownloadRunbookSpec.yml	New Bruno script-based flow to fetch + unpack runbook spec from SAS ZIP.
src/migrate/spec/Runbooks/DeleteRunbookStep.yml	New REST example for deleting a step.
src/migrate/spec/Runbooks/DeleteRunbook.yml	New REST example for deleting a runbook.
src/migrate/spec/Runbooks/CreateRunbook.yml	New REST example for creating/generating a runbook.
src/migrate/spec/Runbooks/AddRunbookStep.yml	New REST example for adding a step.
src/migrate/spec/RunbookExecutions/UpdateRunbookExecutionStepStatus.yml	New REST example for completing a step during execution.
src/migrate/spec/RunbookExecutions/StartRunbookExecution.yml	New REST example for starting an execution.
src/migrate/spec/RunbookExecutions/ProvideRunbookExecutionStepApproval.yml	New REST example for approval action on a step.
src/migrate/spec/RunbookExecutions/PerformRunbookExecutionAction.yml	New REST example for generic execution actions.
src/migrate/spec/RunbookExecutions/PatchRunbookExecution.yml	New REST example for patching execution state.
src/migrate/spec/RunbookExecutions/ListRunbookExecutions.yml	New REST example for listing executions.
src/migrate/spec/RunbookExecutions/GetRunbookExecution.yml	New REST example for showing an execution.
src/migrate/spec/RunbookExecutions/GenerateRunbookExecutionDownloadUrl.yml	New REST example for execution artifact download URL.
src/migrate/spec/RunbookExecutions/DownloadRunbookExecutionStatus.yml	New Bruno script-based flow to fetch + unpack execution status from SAS ZIP.
src/migrate/spec/execution-tracking-example.json	Example execution-tracking/status JSON used for visualization/testing.
src/migrate/setup.py	Version bump + include visualize HTML templates in package data.
src/migrate/linter_exclusions.yml	Exclude resource_group_name parameter from test-coverage linter for migrate runbook.
src/migrate/HISTORY.rst	Add 3.0.0b6 changelog entry for runbook commands.
src/migrate/azext_migrate/tests/latest/runbook/test_runbook_scenario.py	Unit-style scenario tests for runbook CRUD + execution-step actions via mocked ArmClient.
src/migrate/azext_migrate/tests/latest/runbook/test_runbook_recording.py	Recorded/live scenario tests for runbook command group (with SAS scrubbing).
src/migrate/azext_migrate/tests/latest/runbook/recordings/test_runbook_show_and_list.yaml	New cassette for runbook show/list playback.
src/migrate/azext_migrate/tests/latest/runbook/init.py	New test package marker for runbook tests.
src/migrate/azext_migrate/shared/telemetry.py	Best-effort telemetry wrappers for handled exceptions/user faults/events.
src/migrate/azext_migrate/shared/files.py	SAS ZIP download/upload + safe extraction + artifact classification utilities.
src/migrate/azext_migrate/shared/errors.py	ARM error mapping helpers (status->azclierror types).
src/migrate/azext_migrate/shared/constants.py	Shared constants (API versions, ARM id templates).
src/migrate/azext_migrate/shared/arm_ids.py	Helpers to build ARM IDs and append api-version.
src/migrate/azext_migrate/shared/arm_client.py	Central ArmClient wrapper over send_raw_request + LRO polling logic.
src/migrate/azext_migrate/shared/init.py	New shared package marker.
src/migrate/azext_migrate/runbook/visualize/viewmodel.py	Build grid-oriented view model for definition/execution rendering.
src/migrate/azext_migrate/runbook/visualize/templates/runbook.html.tmpl	Offline HTML template for grid + diagram views and UI interactions.
src/migrate/azext_migrate/runbook/visualize/renderer.py	Security-critical HTML rendering (escaping) + SVG layout + help chips + detail drawer.
src/migrate/azext_migrate/runbook/visualize/graph.py	Convert runbook JSON to DAG model with validation and stable layering.
src/migrate/azext_migrate/runbook/visualize/init.py	Visualization package init/docs.
src/migrate/azext_migrate/runbook/validators.py	CLI validators for generate/approve/complete/visualize identity requirements.
src/migrate/azext_migrate/runbook/transformers.py	--output table transformers for runbooks, definitions, executions.
src/migrate/azext_migrate/runbook/params.py	Argument registration for all migrate runbook commands/subgroups.
src/migrate/azext_migrate/runbook/models.py	Request body builders for runbook/definition/execution operations.
src/migrate/azext_migrate/runbook/deps.py	Shared dependency merging/labeling for prerequisites + dependsOn.
src/migrate/azext_migrate/runbook/constants.py	Runbook feature constants (step types, statuses, action codes, terminals).
src/migrate/azext_migrate/runbook/config_status.py	Compute per-step configurationStatus from parameters schema/values.
src/migrate/azext_migrate/runbook/commands.py	Command table registration for new runbook group(s).
src/migrate/azext_migrate/runbook/cmds/runbook.py	Runbook CRUD/regenerate/wait command implementations.
src/migrate/azext_migrate/runbook/cmds/parameter.py	Runbook parameter download/upload via SAS + validation.
src/migrate/azext_migrate/runbook/cmds/execution.py	Execution lifecycle commands + watch + visualize.
src/migrate/azext_migrate/runbook/cmds/execution_step.py	Execution step actions (retry/approve/complete).
src/migrate/azext_migrate/runbook/cmds/execution_parameter.py	Execution input download/upload via SAS.
src/migrate/azext_migrate/runbook/cmds/definition.py	Definition show/download/visualize via artifact service + config annotation.
src/migrate/azext_migrate/runbook/cmds/definition_workstream.py	Workstream split/merge command implementations.
src/migrate/azext_migrate/runbook/cmds/definition_step.py	Step add/update/remove command implementations.
src/migrate/azext_migrate/runbook/cmds/init.py	New cmds package marker.
src/migrate/azext_migrate/runbook/_help.py	CLI help entries for the new runbook command group.
src/migrate/azext_migrate/runbook/init.py	New runbook package marker.
src/migrate/azext_migrate/_params.py	Add -p short option for global --project-name.
src/migrate/azext_migrate/_help.py	Import runbook help module so help is registered.
src/migrate/azext_migrate/init.py	Wire runbook command/argument loaders into the extension loader.
src/migrate/AGENTS.md	New agent guidance + domain facts + verification gate for migrate changes.

Suppressed comments (1)

src/migrate/azext_migrate/runbook/models.py:88

• _depends_on_refs currently emits dependency objects with a mode key. Per the PR’s own documented write contract (AGENTS.md), the service expects the discriminator to be Mode (integer) rather than mode (string), so the current payload shape is inconsistent and likely rejected by the service.

            refs.append(
                {"mode": STEP_DEPENDENCY_MODE_STEP, "stepId": entry})

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Yong Zhang (yonzhan)]

Migrate

[Aditya Pujara (a0x1ab)]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 pipeline(s).

[Aditya Pujara (a0x1ab)]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 pipeline(s).

[Aditya Pujara (a0x1ab)]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 pipeline(s).