Configuration Conditions
What is a Configuration Condition?
Configuration Conditions are used as a way to queue or discard a build if certain expressions evaluate as true or to ensure that shared resources are acquired before queuing a build. When creating a condition, you provide a behaviour, the build type it's applied to, a condition type and a list of conditions. The following image shows the dialog when creating a configuration condition.
Note that Shared Resource Lock conditions are available from version 1.8
Creating and Editing Configuration Conditions
Configuration conditions can be created, edited or deleted within the Conditions step of the Configuration Wizard.
New/Edit Condition
Behaviour
This field defines the behaviour of the build when the conditions are met. You can choose between Queue and Discard.
Queue
A Queue condition controls when a build should begin executing.
If a build is triggered and it contains a Queue condition, Continua will not begin executing the build until all of the queue conditions have been met. The build will simply sit in the build queue and wait for all the queue conditions to be met.
There are two types of Queue conditions: "Expression" and "Shared resource lock". Expression conditions consist of one or more expressions, which must evaluate to true. Shared resource lock conditions consist of one or more shared resource lock quotas which must be acquired.
Continua will immediately begin executing the build once all the queue conditions are met. This is handy for situations where you want to control how and when a configuration is executed.
For example, you could configure a queue condition expression so that no builds run between 9-5. To set this up you would create a queue condition of type Expression and add the expression:$Server.Now.Hour$ Not between 9,16(as seen in the screenshot above). With this condition, any builds in this configuration that were triggered between 9am and 5pm would sit on the queue until 5pm. At this point it would then run all the builds that were waiting on this condition. If a build was triggered outside these hours then it would run as normal.
You could also configure a queue condition to require one of three available licences for a particular application. To set this up, you would first create a Server Shared Resource called "License.XApp", for example. Next, create a queue condition of type "Shared resource lock" and add the identifier: "License.XApp". Select "Read" lock and enter 1 for the number of locks required (as seen in the screenshot below). With this condition, once three builds are running and have acquired a lock on this resource, subsequent build will sit on the queue until one build finishes and releases a shared resource lock.
Discard
A discard condition will stop a build before it is executed if any or all of its expressions evaluate to true, depending on the Expression Logic (see below). Note that discard conditions are always expressions - you cannot have discard conditions based on shared resource locks. The difference between discarding and queuing a build is that a discarded build will never run again while a queued build can run at a later time. Discarding builds is useful when certain types of builds should never get built.
For example, you could configure a discard condition so that it discards all triggered builds that have no new change sets. This can be setup by creating a discard condition that is applied to Triggers with the following expression: $Build.HasNewChanges$ Equals true (as seen in the screenshot above). With this condition, any triggered builds that have no new changes will not be built. This would be useful if you have several time triggers and any new builds would be the same as the previous build.
Accumulate changes
If accumulate changes is ticked, any new changesets which are detected on associated repositories while the build is waiting in the queue, will be added to this build rather than triggering a new build (if a relevant trigger exists).
Applied to
- User: This condition will only be checked when a build is started manually by a user. A build can only be manually started through the Continua interface by pressing the run or quick run buttons on the Configuration pages.
- Triggers: This condition will only be checked if the build was started by a trigger. Triggered builds include repository triggers, time triggers and build completed triggers.
- Any: All builds will evaluate this condition.
Condition Type
Queue conditions can either be of type "Expression" or "Shared resource lock". Selecting "Expression" allow you to enter expressions which can be evaluated as true or false. Selecting "Shared resource lock" will allow you to enter a list of shared resource identifiers along with lock type and number required.
Expressions
Expressions are the individual criteria that will be evaluated to determine whether this condition passes or fails. Expressions take the form of <Left value> <operator> <Right Value>. For example the expression 1 equals 2 will always fail while the expression 1 does not equal 2 will always pass.
Multiple expressions can be linked to each condition by clicking the plus icon to the right of the expressions. Note that expression syntax can be used when setting the left and right values.
Expression Logic
Choose "And" to require that all expressions are true before the condition is met. If "Or" is selected then the condition is met if any of the expression evaluates as true.
Shared Resources
Shared resource locks can be added to the condition by selecting an Identifier. Note that the server shared resources must be set up in the administration area first.
For quota list shared resources, you can then select an operation "Acquire All", "Acquire Any" or "Acquire Specific". Acquire All will attempt to acquire the required number of locks from each and every label of the Shared Resource. Acquire Any will attempt to acquire the required number of locks any one Shared Resource label, checking the label with the highest number available first. Acquire Specific will allow you to specify a Shared Resource Label and will attempt to acquire the required number of locks from the specified Shared Resource label.
If the shared resource has more than a single quota, you can then choose whether to acquire a read or write lock. A read lock can be acquired providing there is no write lock and the number required is available. A write lock can be acquired providing no other read or write locks are held.
When acquiring read locks, you can enter the number required up to the maximum quota.
Add more shared resource locks by clicking the plus icon to the right of the row.
Hold resource lock if a build stage waits for manual promotion
Shared resources locks will be normally be released while a build stage waits for manual promotion. Tick this option to continue to hold on to the resource lock until the build completes - either after promotion or when the promotion times out. Note that this can potentially prevent other builds from running for a long period of time.