Understanding states in Release Management

Divyansh Manchanda — Tue, 25 Jul 2017 18:08:32 GMT

Trying to code against release management APIs? This post will try to demystify the various states that are present in the release object and explain what each of them signify. First, we need to understand the structure of the release object. The release object is a wrapper to a bunch of artifacts and environments. Each environment is what actually gets deployed - and the artifact gives away the details of what got deployed (the bits). The properties that we are mainly concerned with are shown here with the hierarchy - Release - Environments (List of ReleaseEnvironment) - DeploySteps (List of DeploymentAttempt) - ReleaseDeployPhases - ManualInterventions (if any) - PreDeploy Approvals - PostDeploy Approvals A release contains a list of release environments. Each release environment has some static information around what is to be run- the list of tasks and settings. The environment in turn has a list of deploy steps, one per deployment attempt. A deployment attempt is the run time entity which will contain the results of execution of each task. Lets look at the states of each of these layers and figure out what each of them means. Release (release.status)

Draft - The release was created as a draft and no deployment has started yet. You can edit the release object just like you would edit the release definition and then start the release. Any edits made to the release will not impact the release definition.
Active - Once a release has been started it enters the active state. Either deployments are going on the environments or they are waiting to start through an external trigger like a manual deploy action or completion of the previous environment. A release needs to be in active state for users to perform actions on it. An active release has an aritfact linked to it which cannot be modified.
Abandoned - This is the terminal state of the release. No more actions are allowed on abandoned releases.

Release Environment (environment.status)

NotStarted - No deployment has been queued on this environment. Some external signal needs to come in to start the deployment, be it a manual trigger or the completion of some previous environment.
InProgress - The environment has moved out of the pipeline queue. The execution has begun. Do note: the enviroment is in either of the 3 states - pre deployment approval, deploying, post deployment approval.
Succeeded - All good!
Canceled - The deployment on the environment has been canceled by some user.
Rejected - An apporoval was rejected.
Queued - If the queuing policy on the environment is configured in a way that deployment has to wait, the environment state would be marked as queued.
Scheduled - A deployment is scheduled for some later time. (environment.nextScheduledTime will tell you when)

ReleaseEnvironment gives you some information as to where exactly is the deployment as of now. These states are too broad and you would still need to parse the object if you need meaningful info like - "environment is in progress, but is it safe to cancel the deployment now or are the tasks executing already?". To answer questions like these you need to look at the deploymentAttempt object. The deployment attempt object list contains all the run time information about the attempts that were made to deploy to an environment within a release. Every time you click on the deploy/redeploy button the environment a new deploymentAttempt is created. DeploymentAttempt (status, operationStatus) This object has a status and an operationStatus. The status will be like the environment status (broad classification) and the operationStatus will tell you why the deployment is in that state. This is to be read in pairs -

- Queued because of the queueing policy (eg. For "one deployment should be active at a time" policy, the newer deployments will be in this state)
- Environment is scheduled for deployment at a later time.
- Pre deployment approval is pending. environment.predeployApprovals will tell you who is blocking it.
- Pre deployment approval just got approved. The deployment should not be stuck here for long and will move forward automatically.
- This is when the pre depoyment approval got rejected by the user. Again, environment.predeployApprovals will tell you who rejected it.
- The approver did approve the deployment but deferred it to a later time.
- The deployment is ready to run but there is no free agent and it is stuck in the agent queue.
- Oops, you ran out of licenses. The deployment will proceed when a pipeline gets freed up.
- The deployment got canceled before the task execution ran. deployStep.LastModifiedBy will tell you who canceled the deployment.

Do note, the deployment status is marked as InProgress only when the agent picks up task execution. The environment.state on the other hand is marked as inprogress as soon as the pre-approval is created.

- The deployment got picked up by the agent. Task execution has started.
- You had a manual intervention task and the deployment now tells you that. deployStep.releaseDeployPhases[x].ManualInterventions collection will have more details on the manual intervention.
- The deploy phase passed. The next deploy phase would begin execution or a post deployment approval will be created.
- All deploy phases have completed execution. The deployment is waiting on a post-deployment approval.
- The difference between this and is that this will be the state for all phases after the first one has finished execution.
- Yay! All good, tasks passed and approvers approved the release.
- A task that was marked as ContinueOnError failed. The subsequent tasks executed successfully.
- Task failed, or the manual intervention got rejected.
- Someone canceled the deployment after the task execution started and before the deployment could go green. If tasks were executing when this happened environment.PostDeployApprovals should be empty, and if the deployment got canceled when it was pending an approval the collection would have an entry. deployStep.LastModifiedBy will give away details on who canceled the deployment.
- A post deploy approval got rejected.

[Update] There were a few more states introduced in RM so i'm updating the blog to reflect those as well.

- This is the intermediate state between and and happens when a user issues the cancel signal when tasks are executing. The deployment is most likely completing some pending operations before the terminal failed state can be reached. (eg. finish tasks marked as alwaysRun)

States related to RM gates functionality

- Pre deployment gates being evaluated.
- Pre-deployment gates evaluation failed. Whether this is a terminal state or not depends on the gates options (ask for approval always setting will move the release forward)
- Post-deployment gates being evaluated.
OR - Post-deployment gates evaluation failed. Whether this is a terminal state or not (InProgress or Failed status) depends on the gates options (ask for approval always setting will move the release forward).

Adding release management environment templates to your VSS extension

Divyansh Manchanda — Tue, 30 May 2017 17:50:31 GMT

One of the easiest way to create a Release Definition is by using a pre-created environment template. If you have ever authored a release definition, you would have seen this pop-up while adding a new environment - This lets you choose a template from system templates, or you can save your own environment as a template and re-use them while creating new environments. As an author of a vss extension you can now define environment templates which will be available to all users when they install the extension. Steps to add an environment template to your extension

The contribution that the extension needs to target to add environment templates is ms.vss-environmenttemplate.environment-template
All the changes to describe this template go to vss-extension.json file of the extension.
Define your template with the following properties (the payload looks like any other environment template) -
- Id - A guid to uniquely identify your environment template.
- Name - Name of the template that will show up in the popup shown above.
- Description - Describe what the template can do
- Variables - A set of RM variables that the environment will be set up with.
- DeployPhases - A list of the deploy phases that will be executed when the deployment begins. Each deploy phase will have its own set of tasks to be executed by the agent.
Add an icon to represent the template.
Build and install the extension! The template should be available in templates list now.

Link to the Release Management extensions repo on GitHub that has a sample extension published. If you are new to writing extensions, this link will be useful.

Hello world!

Varsha G — Tue, 30 May 2017 10:39:47 GMT

Welcome to Developer Network. This is your first post. Edit or delete it, then start blogging!

Divyansh Manchanda’s Blog

Understanding states in Release Management

Adding release management environment templates to your VSS extension

Hello world!