Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see https://docs.buildbot.net/current/.

2.5.12.1. Parameters Common to all Steps

All BuildSteps accept some common parameters. Some of these control how their individual status affects the overall build. Others are used to specify which Locks (see Interlocks) should be acquired before allowing the step to run.

Note that it is not possible to change the configuration of the BuildStep by adjusting its attributes after construction. Use set_step_arg(name, value) function for that.

Arguments common to all BuildStep subclasses:

name: The name used to describe the step on the status display. Since 0.9.8, this argument might be renderable.

haltOnFailure: If True, a FAILURE of this build step will cause the build to halt immediately. Any steps with alwaysRun=True will still be run. Generally speaking, haltOnFailure implies flunkOnFailure (the default for most BuildSteps). In some cases, particularly with a series of tests, it makes sense to haltOnFailure if something fails early on but not flunkOnFailure. This can be achieved with haltOnFailure=True, flunkOnFailure=False.

flunkOnWarnings: When True, a WARNINGS or FAILURE of this build step will mark the overall build as FAILURE. The remaining steps will still be executed.

flunkOnFailure: When True, a FAILURE of this build step will mark the overall build as a FAILURE. The remaining steps will still be executed.

warnOnWarnings: When True, a WARNINGS or FAILURE of this build step will mark the overall build as having WARNINGS. The remaining steps will still be executed.

warnOnFailure: When True, a FAILURE of this build step will mark the overall build as having WARNINGS. The remaining steps will still be executed.

alwaysRun: If True, this build step will always be run, even if a previous buildstep with haltOnFailure=True has failed.

description: This will be used to describe the command (on the Waterfall display) while the command is still running. It should be a single imperfect-tense verb, like compiling or testing. The preferred form is a single, short string, but for historical reasons a list of strings is also acceptable.

descriptionDone

This will be used to describe the command once it has finished. A simple noun like compile or tests should be used. Like description, this may either be a string or a list of short strings.

If neither description nor descriptionDone are set, the actual command arguments will be used to construct the description. This may be a bit too wide to fit comfortably on the Waterfall display.

All subclasses of BuildStep will contain the description attributes. Consequently, you could add a ShellCommand step like so:

from buildbot.plugins import steps

f.addStep(steps.ShellCommand(command=["make", "test"],
                             description="testing",
                             descriptionDone="tests"))

descriptionSuffix

This is an optional suffix appended to the end of the description (ie, after description and descriptionDone). This can be used to distinguish between build steps that would display the same descriptions in the waterfall. This parameter may be a string, a list of short strings or None.

For example, a builder might use the Compile step to build two different codebases. The descriptionSuffix could be set to projectFoo and projectBar, respectively for each step, which will result in the full descriptions compiling projectFoo and compiling projectBar to be shown in the waterfall.

doStepIf: A step can be configured to only run under certain conditions. To do this, set the step’s doStepIf to a boolean value, or to a function that returns a boolean value or Deferred. If the value or function result is false, then the step will return SKIPPED without doing anything. Otherwise, the step will be executed normally. If you set doStepIf to a function, that function should accept one parameter, which will be the BuildStep object itself.

hideStepIf

A step can be optionally hidden from the waterfall and build details web pages. To do this, set the step’s hideStepIf to a boolean value, or a function that takes two parameters (the results and the BuildStep) and returns a boolean value. Steps are always shown while they execute; however, after the step has finished, this parameter is evaluated (if it’s a function), and if the value is true, the step is hidden. For example, in order to hide the step if the step has been skipped:

factory.addStep(Foo(..., hideStepIf=lambda results, s: results==SKIPPED))

locks: A list of Locks (instances of buildbot.locks.WorkerLock or buildbot.locks.MasterLock) that should be acquired before starting this BuildStep. Alternatively, this could be a renderable that returns this list during build execution. This lets you defer picking the locks to acquire until the build step is about to start running. The Locks will be released when the step is complete. Note that this is a list of actual Lock instances, not names. Also note that all Locks must have unique names. See Interlocks.

logEncoding: The character encoding to use to decode logs produced during the execution of this step. This overrides the default logEncoding; see Log Handling.

updateBuildSummaryPolicy

The policy to use to propagate the step summary to the build summary. If False, the build summary will never include the step summary. If True, the build summary will always include the step summary. If set to a list (e.g. [FAILURE, EXCEPTION]), the step summary will be propagated if the step results id is present in that list. If not set or None, the default is computed according to other BuildStep parameters using following algorithm:

self.updateBuildSummaryPolicy = [EXCEPTION, RETRY, CANCELLED]
if self.flunkOnFailure or self.haltOnFailure or self.warnOnFailure:
    self.updateBuildSummaryPolicy.append(FAILURE)
if self.warnOnWarnings or self.flunkOnWarnings:
    self.updateBuildSummaryPolicy.append(WARNINGS)

Note that in a custom step, if BuildStep.getResultSummary is overridden and sets the build summary, updateBuildSummaryPolicy is ignored and the build summary will be used regardless.