az changesafety changerecord

Note

This reference is part of the azure-changesafety extension for the Azure CLI (version 2.75.0 or higher). The extension will automatically install the first time you run an az changesafety changerecord command. Learn more about extensions.

Manage ChangeRecord resources that describe planned changes across targets.

Commands

Name	Description	Type	Status
az changesafety changerecord create	Create a ChangeRecord resource.	Extension	GA
az changesafety changerecord delete	Delete a ChangeRecord resource.	Extension	GA
az changesafety changerecord list	List ChangeRecord resources.	Extension	GA
az changesafety changerecord show	Show details for a ChangeRecord resource.	Extension	GA
az changesafety changerecord update	Update an existing ChangeRecord resource.	Extension	GA

az changesafety changerecord create

Create a ChangeRecord resource.

Provide at least one target definition to describe which resources or operations the ChangeRecord will affect. Targets are expressed as comma or semicolon separated key=value pairs such as resourceId=RESOURCE_ID,operation=DELETE. The command is also available through the alias az changesafety changerecord. If you omit scheduling flags, the anticipated start time defaults to now and the anticipated end time defaults to eight hours later (UTC).

az changesafety changerecord create --change-record-name --name
                                    [--acquire-policy-token]
                                    [--additional-data]
                                    [--anticipated-end-time]
                                    [--anticipated-start-time]
                                    [--change-definition]
                                    [--change-reference]
                                    [--change-type {AppDeployment, Config, ManualTouch, PolicyDeployment}]
                                    [--comments]
                                    [--description]
                                    [--links]
                                    [--orchestration-tool]
                                    [--parameters]
                                    [--release-label]
                                    [--resource-group]
                                    [--rollout-type {Emergency, Hotfix, Normal}]
                                    [--stage-map]
                                    [--stage-map-name --stagemap-name]
                                    [--targets]

Examples

Create a ChangeRecord for deleting a Traffic Manager profile

az changesafety changerecord create -g MyResourceGroup -n delete-trafficmanager --change-type ManualTouch --rollout-type Hotfix --targets "resourceId=/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyResourceGroup/providers/Microsoft.Network/trafficManagerProfiles/myProfile,operation=DELETE" --description "Delete Traffic Manager profile"

Reference a StageMap by name

az changesafety changerecord create -g MyResourceGroup -n changerecord003 --change-type ManualTouch --rollout-type Normal --stagemap-name rolloutStageMap --targets "resourceId=/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyResourceGroup/providers/Microsoft.Compute/virtualMachines/myVm,operation=DELETE"

Create with StageMap reference and status link

az changesafety changerecord create -g MyResourceGroup -n changerecord002 --change-type ManualTouch --rollout-type Normal --stage-map "{resource-id:/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.ChangeSafety/stageMaps/rolloutStageMap}" --targets "resourceId=/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MyResourceGroup/providers/Microsoft.Compute/virtualMachines/myVm,operation=PATCH" --links "[{name:status,uri:'https://contoso.com/change/rollout-002'}]"
az changesafety changerecord delete -g MyResourceGroup -n changerecord002 --yes

Create at subscription scope (no resource group)

az changesafety changerecord create -n changerecord-sub-scope --change-type AppDeployment --rollout-type Normal --stagemap-name rolloutStageMap --targets "subscriptionId=00000000-0000-0000-0000-000000000000"

Required Parameters

--change-record-name --name -n

The name of the ChangeRecord resource.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--additional-data

Additional metadata for the change required for various orchestration tools. Support shorthand-syntax, json-file and yaml-file. Try "??" to show more.

Property	Value
Parameter group:	Properties Arguments

--anticipated-end-time

Expected completion time in ISO 8601 format. Defaults to eight hours after the anticipated start time when omitted.

Property	Value
Parameter group:	Properties Arguments

--anticipated-start-time

Expected start time in ISO 8601 format. Defaults to current UTC time when omitted.

Property	Value
Parameter group:	Properties Arguments

--change-definition

Change request body and/or resource selection criteria used to identify the targeted resources. Support shorthand-syntax, json-file and yaml-file. Try "??" to show more.

Property	Value
Parameter group:	Properties Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-type

Classify the change such as AppDeployment, Config, ManualTouch, or PolicyDeployment.

Property	Value
Parameter group:	Properties Arguments
Accepted values:	AppDeployment, Config, ManualTouch, PolicyDeployment

--comments

Comments about the last update to the ChangeRecord resource.

Property	Value
Parameter group:	Properties Arguments

--description

A description of the change being performed.

Property	Value
Parameter group:	Properties Arguments

--links

Add supporting links by repeating --links name=NAME uri=URL [description=TEXT].

Property	Value
Parameter group:	Properties Arguments

--orchestration-tool

Tool used for deployment orchestration of this change.

Property	Value
Parameter group:	Properties Arguments

--parameters

Schema of parameters that will be provided for each stageProgression. Support shorthand-syntax, json-file and yaml-file. Try "??" to show more.

Property	Value
Parameter group:	Properties Arguments

--release-label

Label for the release associated with this change.

Property	Value
Parameter group:	Properties Arguments

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--rollout-type

Specify the rollout type (Normal, Hotfix, or Emergency).

Property	Value
Parameter group:	Properties Arguments
Accepted values:	Emergency, Hotfix, Normal

--stage-map

Reference an existing StageMap resource using resource-id=RESOURCE_ID and optional parameters key=value pairs.

Property	Value
Parameter group:	Properties Arguments

--stage-map-name --stagemap-name

StageMap name in the current subscription scope; the resource ID is built for you.

Property	Value
Parameter group:	Properties Arguments

--targets

One or more target definitions expressed as key=value pairs (for example resourceId=RESOURCE_ID,operation=DELETE,resourceType=Microsoft.Compute/virtualMachines).

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az changesafety changerecord delete

Delete a ChangeRecord resource.

az changesafety changerecord delete [--acquire-policy-token]
                                    [--change-record-name --name]
                                    [--change-reference]
                                    [--ids]
                                    [--resource-group]
                                    [--subscription]
                                    [--yes]

Examples

Delete a ChangeRecord without confirmation

az changesafety changerecord delete -g MyResourceGroup -n changerecord001 --yes

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-record-name --name -n

The name of the ChangeRecord resource.

Property	Value
Parameter group:	Resource Id Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

Property	Value
Parameter group:	Resource Id Arguments

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Property	Value
Parameter group:	Resource Id Arguments

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

Property	Value
Parameter group:	Resource Id Arguments

--yes -y

Do not prompt for confirmation.

Property	Value
Default value:	False

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az changesafety changerecord list

List ChangeRecord resources.

List all ChangeRecord resources in a subscription or resource group.

az changesafety changerecord list [--max-items]
                                  [--next-token]
                                  [--resource-group]

Examples

List all ChangeRecords in the current subscription

az changesafety changerecord list

List ChangeRecords in a specific resource group

az changesafety changerecord list -g MyResourceGroup

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--max-items

Total number of items to return in the command's output. If the total number of items available is more than the value specified, a token is provided in the command's output. To resume pagination, provide the token value in --next-token argument of a subsequent command.

Property	Value
Parameter group:	Pagination Arguments

--next-token

Token to specify where to start paginating. This is the token value from a previously truncated response.

Property	Value
Parameter group:	Pagination Arguments

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az changesafety changerecord show

Show details for a ChangeRecord resource.

az changesafety changerecord show [--change-record-name --name]
                                  [--ids]
                                  [--resource-group]
                                  [--subscription]

Examples

Show a ChangeRecord

az changesafety changerecord show -g MyResourceGroup -n changerecord001

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--change-record-name --name -n

The name of the ChangeRecord resource.

Property	Value
Parameter group:	Resource Id Arguments

--ids

Property	Value
Parameter group:	Resource Id Arguments

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Property	Value
Parameter group:	Resource Id Arguments

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

Property	Value
Parameter group:	Resource Id Arguments

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

az changesafety changerecord update

Update an existing ChangeRecord resource.

Use this command to modify descriptive metadata, rollout settings, or scheduling for an existing ChangeRecord. Note: The changeDefinition (targets) cannot be modified after creation.

az changesafety changerecord update [--acquire-policy-token]
                                    [--add]
                                    [--additional-data]
                                    [--anticipated-end-time]
                                    [--anticipated-start-time]
                                    [--change-record-name --name]
                                    [--change-reference]
                                    [--change-type {AppDeployment, Config, ManualTouch, PolicyDeployment}]
                                    [--comments]
                                    [--description]
                                    [--force-string {0, 1, f, false, n, no, t, true, y, yes}]
                                    [--ids]
                                    [--links]
                                    [--orchestration-tool]
                                    [--parameters]
                                    [--release-label]
                                    [--remove]
                                    [--resource-group]
                                    [--rollout-type {Emergency, Hotfix, Normal}]
                                    [--set]
                                    [--stage-map]
                                    [--stage-map-name --stagemap-name]
                                    [--subscription]

Examples

Adjust rollout type and add a comment

az changesafety changerecord update -g MyResourceGroup -n changerecord001 --rollout-type Emergency --comments "Escalated to emergency rollout"

Update scheduling window

az changesafety changerecord update -g MyResourceGroup -n changerecord001 --anticipated-start-time "2026-09-01T08:00:00Z" --anticipated-end-time "2026-09-01T12:00:00Z"

Update description

az changesafety changerecord update -g MyResourceGroup -n changerecord001 --description "Updated rollout for production deployment"

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--add

Add an object to a list of objects by specifying a path and key value pairs. Example: --add property.listProperty <key=value, string or JSON string>.

Property	Value
Parameter group:	Generic Update Arguments

--additional-data

Additional metadata for the change required for various orchestration tools. Support shorthand-syntax, json-file and yaml-file. Try "??" to show more.

Property	Value
Parameter group:	Properties Arguments

--anticipated-end-time

Update the expected completion time in ISO 8601 format. If omitted, the current value is preserved.

Property	Value
Parameter group:	Properties Arguments

--anticipated-start-time

Update the expected start time in ISO 8601 format. If omitted, the current value is preserved.

Property	Value
Parameter group:	Properties Arguments

--change-record-name --name -n

The name of the ChangeRecord resource.

Property	Value
Parameter group:	Resource Id Arguments

--change-reference

The related change reference ID for this resource operation.

Property	Value
Parameter group:	Global Policy Arguments

--change-type

Describes the nature of the change.

Property	Value
Parameter group:	Properties Arguments
Accepted values:	AppDeployment, Config, ManualTouch, PolicyDeployment

--comments

Provide notes about the latest update to the ChangeRecord.

Property	Value
Parameter group:	Properties Arguments

--description

Update the description of the change.

Property	Value
Parameter group:	Properties Arguments

--force-string

When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.

Property	Value
Parameter group:	Generic Update Arguments
Accepted values:	0, 1, f, false, n, no, t, true, y, yes

--ids

Property	Value
Parameter group:	Resource Id Arguments

--links

Collection of related links for the change. Support shorthand-syntax, json-file and yaml-file. Try "??" to show more.

Property	Value
Parameter group:	Properties Arguments

--orchestration-tool

Tool used for deployment orchestration of this change.

Property	Value
Parameter group:	Properties Arguments

--parameters

Schema of parameters that will be provided for each stageProgression. Support shorthand-syntax, json-file and yaml-file. Try "??" to show more.

Property	Value
Parameter group:	Properties Arguments

--release-label

Label for the release associated with this change.

Property	Value
Parameter group:	Properties Arguments

--remove

Remove a property or an element from a list. Example: --remove property.list <indexToRemove> OR --remove propertyToRemove.

Property	Value
Parameter group:	Generic Update Arguments

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Property	Value
Parameter group:	Resource Id Arguments

--rollout-type

Describes the type of the rollout used for the change.

Property	Value
Parameter group:	Properties Arguments
Accepted values:	Emergency, Hotfix, Normal

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=<value>.

Property	Value
Parameter group:	Generic Update Arguments

--stage-map

Reference an existing StageMap resource using resource-id=RESOURCE_ID and optional parameters key=value pairs.

Property	Value
Parameter group:	Properties Arguments

--stage-map-name --stagemap-name

StageMap name in the current subscription scope; the resource ID is built for you.

Property	Value
Parameter group:	Properties Arguments

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

Property	Value
Parameter group:	Resource Id Arguments

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

Property	Value
Default value:	False

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property	Value
Default value:	False

--output -o

Output format.

Property	Value
Default value:	json
Accepted values:	json, jsonc, none, table, tsv, yaml, yamlc

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property	Value
Default value:	False

Feedback

Was this page helpful?