Azure DevOps Pipeline - Release API - Update Release Definition add and remove a templated stage

Question

We have a Azure DevOps Pipeline Release Definition, and i am looking at putting in place some automation for a new 'Stage' to be created from a template when a pull request is triggered on branch x, and the stage to be removed when the branch is deleted. i will be using github actions for this.

The API doc's are not super easy to follow.

My question are:

• is this possible, dose the API support making such adding and removing of stage's to a _releaseDefinition ?

• if so is there any examples on how to do this ?

Doc's https://learn.microsoft.com/en-us/rest/api/azure/devops/release/releases/update%20release?view=azure-devops-rest-5.1#releasedefinitionshallowreference

Answer 1

The api you should use is Update-definition api:

PUT https://vsrm.dev.azure.com/{org name}/{project name}/_apis/release/definitions?api-version=5.1

For the request body of adding stage/removing stage, it in fact only made changes into environments parameter:

One stage definition corresponds to one grey code block.

Adding stage: Add a template JSON code block of stage definition(the grey one display in my left screenshots). This code structure is fixed.

Removing stage: Remove the complete corresponding stage definition.

---

Here is the one complete stage definition sample:

 {
            "id": -1,
            "name": "Stage 3",
            "rank": 3,
            "variables": {},
            "variableGroups": [],
            "preDeployApprovals": {
                "approvals": [
                    {
                        "rank": 1,
                        "isAutomated": true,
                        "isNotificationOn": false,
                        "id": 7
                    }
                ],
                "approvalOptions": {
                    "requiredApproverCount": null,
                    "releaseCreatorCanBeApprover": false,
                    "autoTriggeredAndPreviousEnvironmentApprovedCanBeSkipped": false,
                    "enforceIdentityRevalidation": false,
                    "timeoutInMinutes": 0,
                    "executionOrder": "beforeGates"
                }
            },
            "deployStep": {
                "id": 8
            },
            "postDeployApprovals": {
                "approvals": [
                    {
                        "rank": 1,
                        "isAutomated": true,
                        "isNotificationOn": false,
                        "id": 9
                    }
                ],
                "approvalOptions": {
                    "requiredApproverCount": null,
                    "releaseCreatorCanBeApprover": false,
                    "autoTriggeredAndPreviousEnvironmentApprovedCanBeSkipped": false,
                    "enforceIdentityRevalidation": false,
                    "timeoutInMinutes": 0,
                    "executionOrder": "afterSuccessfulGates"
                }
            },
            "deployPhases": [
                {
                    "deploymentInput": {
                        "parallelExecution": {
                            "parallelExecutionType": "none"
                        },
                        "agentSpecification": {
                            "identifier": "vs2017-win2016"
                        },
                        "skipArtifactsDownload": false,
                        "artifactsDownloadInput": {
                            "downloadInputs": []
                        },
                        "queueId": 247,
                        "demands": [],
                        "enableAccessToken": false,
                        "timeoutInMinutes": 0,
                        "jobCancelTimeoutInMinutes": 1,
                        "condition": "succeeded()",
                        "overrideInputs": {}
                    },
                    "rank": 1,
                    "phaseType": "agentBasedDeployment",
                    "name": "Agent job",
                    "refName": null,
                    "workflowTasks": []
                }
            ],
            "environmentOptions": {
                "emailNotificationType": "OnlyOnFailure",
                "emailRecipients": "release.environment.owner;release.creator",
                "skipArtifactsDownload": false,
                "timeoutInMinutes": 0,
                "enableAccessToken": false,
                "publishDeploymentStatus": true,
                "badgeEnabled": false,
                "autoLinkWorkItems": false,
                "pullRequestDeploymentEnabled": false
            },
            "demands": [],
            "conditions": [],
            "executionPolicy": {
                "concurrencyCount": 1,
                "queueDepthCount": 0
            },
            "schedules": [],
            "owner": {
        "displayName": "{user name}",
        "id": "{user id}",
        "isContainer": false,
        "uniqueName": "{creator account}",
        "url": "https://dev.azure.com/{org name}/"
      },
            "retentionPolicy": {
                "daysToKeep": 30,
                "releasesToKeep": 3,
                "retainBuild": true
            },
            "processParameters": {},
            "properties": {
                "BoardsEnvironmentType": {
                    "$type": "System.String",
                    "$value": "unmapped"
                },
                "LinkBoardsWorkItems": {
                    "$type": "System.String",
                    "$value": "False"
                }
            },
            "preDeploymentGates": {
                "id": 0,
                "gatesOptions": null,
                "gates": []
            },
            "postDeploymentGates": {
                "id": 0,
                "gatesOptions": null,
                "gates": []
            },
            "environmentTriggers": [],
            "badgeUrl": "https://vsrm.dev.azure.com/{org}/_apis/{project name}/Release/badge/3c3xxx6414512/2/3"
        },

Here has some key parameters you need pay attention: id, owner, rank and conditions.

id: This is the stage id you specified to stage, its value must less than 1. Any value that less than 1 is okay here.

owner: This is required. Or you will receive the message that notify you the stage must has owner.

rank: The natural numbers greater than 1. Here I suggest you increment it based on other stages.

conditions: This is the one which you can configure which stage the current new one will depend on. The nutshell is it used to specify stage execution location of release.

When you updating release, you must pack and set the whole release definition as request body. Get the original one, add new customized stage definition part into it. Then update to api.

---

In fact, I suggest you do adding a stage with UI for test. Then go History tab of release definition page. Then choose Compare difference of three dots.

We provided you the difference of definition in the panel(left panel is the original, the right is updated), and you can clearly get what you should focus on to apply your idea.