The following build properties are set when the build is started, and
are available to all steps.

got_revision

This property is set when a Source step checks out the source tree, and provides the revision that was actually obtained from the VC system.
In general this should be the same as revision, except for non-absolute sourcestamps, where got_revision indicates what revision was current when the checkout was performed.
This can be used to rebuild the same source code later.

Note

For some VC systems (Darcs in particular), the revision is a
large string containing newlines, and is not suitable for interpolation
into a filename.

For multi-codebase builds (where codebase is not the default ''), this property is a dictionary, keyed by codebase.

buildername

This is a string that indicates which Builder the build was a part of.
The combination of buildername and buildnumber uniquely identify a
build.

buildnumber

Each build gets a number, scoped to the Builder (so the first build
performed on any given Builder will have a build number of 0). This
integer property contains the build's number.

slavename

This is a string which identifies which buildslave the build is
running on.

scheduler

If the build was started from a scheduler, then this property will
contain the name of that scheduler.

workdir

The absolute path of the base working directory on the slave, of the current
builder.

For single codebase builds, where the codebase is '', the following Source Stamp Attributes are also available as properties: branch, revision, repository, and project .

For the most part, properties are used to alter the behavior of build steps
during a build. This is done by annotating the step definition in
master.cfg with placeholders. When the step is executed, these
placeholders will be replaced using the current values of the build properties.

Note

Properties are defined while a build is in progress; their values are
not available when the configuration file is parsed. This can sometimes
confuse newcomers to Buildbot! In particular, the following is a common error:

ifProperty('release_train')=='alpha':f.addStep(...)

This does not work because the value of the property is not available when
the if statement is executed. However, Python will not detect this as
an error - you will just never see the step added to the factory.

You can use build properties in most step parameters. Please file bugs for any
parameters which do not accept properties.

The default value is used when the property doesn't exist, or when the value is
something Python regards as False. The defaultWhenFalse argument can be
set to False to force buildbot to use the default argument only if the
parameter is not set:

Property can only be used to replace an entire argument: in the
example above, it replaces an argument to echo. Often, properties need to
be interpolated into strings, instead. The tool for that job is
Interpolate.

The more common pattern is to use Python dictionary-style string interpolation by using the %(prop:<propname>)s syntax.
In this form, the property name goes in the parentheses, as above.
A common mistake is to omit the trailing "s", leading to a rather obscure error from Python ("ValueError: unsupported format character").

This example will result in a make command with an argument like
REVISION=12098.

The syntax of dictionary-style interpolation is a selector, followed by a colon, followed by a selector specific key, optionally followed by a colon and a string indicating how to interpret the value produced by the key.

The following selectors are supported.

prop

The key is the name of a property.

src

The key is a codebase and source stamp attribute, separated by a colon.

kw

The key refers to a keyword argument passed to Interpolate.

slave

The key to the per-buildslave "info" dictionary (e.g., the "Slave information" properties shown
in the buildslave web page for each buildslave)

The following ways of interpreting the value are available.

-replacement

If the key exists, substitute its value; otherwise,
substitute replacement. replacement may be empty
(%(prop:propname:-)s). This is the default.

~replacement

Like -replacement, but only substitutes the value
of the key if it is something Python regards as True.
Python considers None, 0, empty lists, and the empty string to be
false, so such values will be replaced by replacement.

Ternary substitution, depending on either the key being present (with
?, similar to +) or being True (with #?, like ~).
Notice that there is a pipe immediately following the question mark and
between the two substitution alternatives. The character that follows the
question mark is used as the delimiter between the two alternatives. In the
above examples, it is a pipe, but any character other than ( can be used.

Although these are similar to shell substitutions, no other substitutions are currently supported.

In addition, Interpolate supports using positional string interpolation.
Here, %s is used as a placeholder, and the substitutions (which may themselves be placeholders), are given as subsequent arguments:

TODO

Note

Like Python, you can use either positional interpolation or
dictionary-style interpolation, not both. Thus you cannot use a string
like Interpolate("foo-%(src::revision)s-%s","branch").

While Interpolate can handle many simple cases, and even some common conditionals, more complex cases are best handled with Python code.
The renderer decorator creates a renderable object that will be replaced with the result of the function, called when the step it's passed to begins.
The function receives an IProperties object, which it can use to examine the values of any and all properties. For example:

If this BuildStep were used in a tree obtained from Git, it would
create a tarball with a name like
build-master-a7d3a333db708e786edb34b6af646edd8d4d3ad9.tar.gz.

The more common pattern is to use Python dictionary-style string interpolation
by using the %(propname)s syntax. In this form, the property name goes in
the parentheses, as above. A common mistake is to omit the trailing "s",
leading to a rather obscure error from Python ("ValueError: unsupported format
character").

Like propname:-replacement, but only substitutes the value
of property propname if it is something Python regards as True.
Python considers None, 0, empty lists, and the empty string to be
false, so such values will be replaced by replacement.

If the options described above are not sufficient, more complex substitutions can be achieved by writing custom renderables.

Renderables are objects providing the IRenderable interface.
That interface is simple - objects must provide a getRenderingFor method.
The method should take one argument - an IProperties provider - and should return a string or a deferred firing with a string.
Pass instances of the class anywhere other renderables are accepted.
For example: