Work Item Gate

The Work Item Validation Gate provides several variations for ensuring that Work Items associated to the Release have met certain criteria before the Pipeline Execution can continue.

Which Work Items are validated

It is important to understand which Work Items are considered during this Gate evaluation. There are two main categories of Work Items when it comes to Release and Pipeline execution:

Release Work Items - All Work Items ever associated to the Release (these show up under the Work Items section on the Release Definition tab).
Snapshot Work Items - These are the Work Items that were associated during build of the current Release Snapshot. These are generally a subset of the Release Work Items.

When the Work Item Validation Gate is running it is considering Snapshot Work Items.

Validation Types

The Work Item Validation Gate supports 3 Validation Types:

Match Status Exact

The most common use case for the Work Item Validation Gate is making sure each Work Item is in a certain status. The Match Status Exact validator does exactly that. One or more status can be provided, separated by comma, and as long as all Work Items in the Release match at least one of the provided statuses then the Gate will succeed.

Note that the status matching is case insensitive, so a status of DONE will also match a status of done

Match Status Regex

Similar to the Match Status Exact validator, the Match Status Regex validator ensures that each Work Item is in an appropriate status. However, it matches the status based on the provided regex pattern.

Custom

The final validator is the Custom validator. This validator offers a Groovy Script with an exposed WorkItems variable, this allows more complex validations to be done on each Work Item.

The following script is the default script when choosing the Custom Validator - it can be modified as needed.

// the script should return a map with the format [workItemNumber: true/false]
// the following script is valid and can be modified as needed
def resultMap = [:]
for (def workitem : WorkItems)
{
    if ("DONE" == workitem.getStatus())
    {
        // valid work item
        resultMap.put(workitem.getKey(), true)
    }
    else
    {
        // invalid work item
        resultMap.put(workitem.getKey(), false)
    }
}
return resultMap

A few noteworthy comments on using the Custom Validator:

It has access to the WorkItems variable. This variable is a list of WorkItemDetails objects which have all of the information about the Work Item pre-populated such as the assignee, status, labels and more.
The script should return a map with the format [workItemNumber: true/false]

Should the custom script not return a status for a particular WorkItem in the WorkItems variable then it will be considered as false (invalid) when processing the results.

Viewing the Results

During Pipeline Execution, the results of the Work Item Validation gate can be seen in the step details:

Once each Work Item has the valid checkmark next to it, the Gate will be considered successful and continue the Pipeline Execution.

The Gate will remain in a running state, re-evaluating Work Items at a fixed interval as long as there are invalid Work Items.