IF var in LIST THEN
Runs the ops nested underneath it when one stash value matches any entry in a
comma-separated list you type into the form. It is IF var THEN repeated
across several accepted values, with the same exact-text, case-sensitive comparison and the same
absence of ${var} expansion.
The list is split on commas and nothing else. Nothing is trimmed, nothing is expanded, and an entry
cannot itself contain a comma. If those bite you, the IN operator in
IF var condition THEN does the same job and adds case folding
plus ${var} expansion on the list.
Fields¶
Variable¶
The name of the stash value to read, written on its own with no ${} wrapper. Dots walk into
nested values (topic.category) and square brackets index a list (changesets[0].name). A path
that does not resolve gives back nothing and raises no error.
The field is a multi-line monospace text area rather than a single-line box, so a trailing space or a stray newline is easy to leave behind and will stop the lookup from finding anything.
Leave Variable empty and the lookup returns nothing at all, which can only ever match an empty entry in the list.
Values¶
The accepted values, separated by commas.
Commas are the only separator. Spaces around them are kept as part of the entries, so PROD, PRE
accepts PROD and the four characters space P R E, and the second entry never matches anything a
job would put in the stash. Type PROD,PRE with no spaces.
Newlines are not separators either. One value per line gives you entries with a newline stuck to them, and none of them match.
Leave Values empty and the rule breaks. It does not evaluate to false, it fails when the rule starts, before any op has run, so the whole rule stops rather than that branch. An imported or hand-edited rule with an empty list behaves the same way.
A leading comma creates an empty first entry, and an empty entry matches a variable that is unset or
holds an empty string. ,PROD therefore runs the block on every job where the variable was never
set. A trailing comma is harmless and is dropped.
Nothing in this field expands. ${env} is six literal characters here, not the value of env.
How the comparison behaves¶
Each entry is compared for exact text equality, case sensitive, in the order you typed them, and the
first match ends the test. PROD does not match prod. 1.0 does not match 1.
When the variable holds a list or a hash rather than a single value, it matches no entry and the block never runs.
What it does at run time¶
The op holds nested ops like the rest of the IF family. With nothing dropped inside it, the test is evaluated and nothing happens, which is a quiet way to lose a branch during a reshuffle of the tree.
It appears in the job log as a step under whatever you named it, with ${var} placeholders in that
name expanded, and it is one of the points at which a cancel request on the job is noticed. It
writes nothing into the stash.
Its Options tab is cut down to Enabled and Debug Mode. Because it is an IF block, the settings
that wrap extra work around an op are not offered here at all: Return Key, Needs Rollback?,
Run Forward, Run Rollback, Timeout, Semaphore Key, Parallel Mode, Error Handling,
Sub Name and Stage Name are all absent. Put them on the ops nested inside instead, and see
Rule Palette for what each one does.
ELSE and ELSIF condition THEN attach directly after it and take the other side.
On a rollback pass the rule runs again from the top and the list is tested again against the stash as it stands then.
Combining with other ops¶
IF var condition THEN is the better home for this test once the
list stops being a handful of fixed code words. Its IN row takes the same comma-separated list but
adds Ignore case, and its Value field expands ${var}, so the list itself can come from a global
variable.
Use HAS in that same op when the situation is reversed and the list lives in the stash while the
single value is the one you type.
SET VAR before the test is the usual fix for case: normalise the value into a second key and compare against that.
Examples¶
Run a block on two environment codes.
Variable bl
Values PROD,PRE
Restrict a block to a set of topic categories, having loaded the topic earlier in the rule.
Variable topic.category
Values incident,problem,change