Introduction

Conditional tasks allow you put logic into your build, which can help in avoiding a proliferation of plans, or wrapping everything with script tasks.

The principle of conditional tasks, is that if the condition evaluates to true, the tasks following it in the job will be executed, if false they will be skipped.

By default all tasks from the conditional task to the end of the job are in scope for being skipped, however you can configure the conditional task such that it will only execute or skip the next task, or any number of subsequent tasks.

A user with global administration permissions can write conditional tasks using a groovy script. Due to security considerations, non-admins cannot. They can, however, configure the number of tasks to be skipped and change the ordering of the configurable tasks.

To access these tasks choose Add Task, then select ScriptRunner Conditions.

Order of execution

All these conditional tasks are executed when the job is queued. That means that even if there are previous tasks in the job, the conditional task will be evaluated first to determine which of the tasks in the job should execute. This may be surprising if your conditional task occurs late in the job.

Build Variable Filtering Task

This task let’s you conditionally execute subsequent tasks depending on build variables. You can use a simple expression to check if a build variable has a particular value, or more complex expressions where you can use boolean logic.

Under the covers, the expression is evaluated as a groovy script (however for security reasons you are restricted to simple operations on build variables only). This means that only build variable names that are valid groovy variable names can be used. For build variables that don’t fit this pattern you can access them as vars[variable.name], for example vars["planRepository.1.branch"].

As there can be multiple repositories for a plan, there is not necessarily one branch, but possibly many. planRepository.1.branch means "the branch for the first repository".

Further examples can be found by clicking Expand Examples underneath the expression text.

Path Filtering Task

The path filtering tasks will only execute subsequent tasks if the commit(s) that triggered the build contained files matching certain paths. These paths are provided in the form of ant globs, a simple way for matching paths.

For example, you may have a slow multi-module maven build. If all the files changed are in a single module, perhaps you wish to only build and run the tests for that module. Similarly, if only .md files have changed, perhaps you want to only rebuild your documentation.

Custom Script Condition

Custom script conditions can only be created by users with the global administrator permission, and the same permission is required to update the script that they run.

If the script returns true, or a truthy value, the subsequent tasks will be executed. If not, they will be skipped.

As mentioned earlier, the code for all conditional tasks runs on the server, before any task in the job is actually executed. The reason for this is that on the server you have access to the full Bamboo API, rather than just a subset as on a remote agent. Also, most things that you would want to check can actually be done when a job is first scheduled, rather than during execution.

If your users ask for a variation of the same logic, you can create a "canned" filtering task, in the same way as the two above. Contact us if you can’t work out how to implement the logic you need for skipping tasks.

For how-to questions please ask on Atlassian Answers where there is a very active community. Adaptavist staff are also likely to respond there.

Ask a question about ScriptRunner for JIRA, for for Bitbucket Server, or for Confluence.