Build Features and Failure Conditions

A build feature allows modifying behavior of a build on the server or on the agent side.
There is no specific workflow associated with a build feature; a plugin implementing a build feature can plug itself into various listeners and somehow affect the build.

An example of a build feature is XML Report processing. This build feature detects various XML reports on the agent while a build is running, parses them, and imports results into TeamCity server.

Build Feature

To add a custom build feature, one should inherit it from jetbrains.buildServer.serverSide.BuildFeature. The class should be registered as a Spring bean in the plugin spring context.

In general, build features are similar to runners and triggers. For instance, they also have a type which should be unique among all features; besides, the methods working with parameters are almost the same.

However, there are some methods that may require additional description:

isMultipleFeaturesPerBuildTypeAllowed: in most of the cases there can be only one build feature defined per build configuration, but if this is not the case, then this method should return false
getPlaceToShow: this method determines in which part of the administration interface this feature should be configured, use FAILURE_REASON if the build feature is a failure condition and should be configured where all failure conditions reside
isRequiresAgent: some features do not have an agent part and do not require agents to operate. If so, this method should return false
getRequirements: if a build feature has an agent part, with help of this method it is possible to affect agents available to a build where this feature is configured

Accessing Build Features via SBuildType

Once a build feature is configured in a build configuration, it is possible to access it with the following methods of SBuildType:

getBuildFeatures returns the whole set of configured build features (including disabled)
getBuildFeaturesOfType returns only the build features of a specified type (including disabled)
findBuildFeatureById: each build feature has an internal ID associated with it, so this method can be used to find a feature by such an ID

Resolving Parameters

Build features can have parameter references in their settings (for instance, %some.path%), but methods like SBuildType#getBuildFeatures or SBuildType#getBuildFeaturesOfType return build features with unresolved parameters. This is because build features parameters can depend on parameters from agents, and, in general, without an agent it is not clear how parameters resolution should be performed.

Still, it is possible to retrieve features with all parameters resolved by taking only the server-side parameters into account via SBuildType#getResolvedSettings.

Accessing Build Features via SBuild

The following method can be used to retrieve build features of a running or finished build:

getBuildFeaturesOfType: this method returns build features of a specified type with all parameters resolved according to the currently known parameters of the agent where the build is running; only enabled features are returned

Accessing Build Features on Agent

On the agent side, a build is represented by the AgentRunningBuild interface.

To access build features, the following methods can be used:

Both of these methods work similarly to the methods in SBuild, i.e. they return features with all parameters resolved and they don't return disabled features.

Useful Listeners

There is no workflow associated with build features. If a build feature is configured in a build configuration and its method isRequiresAgent returns true, then its settings are automatically delivered to an agent or can be retrieved on the server side from an instance of SBuild.

As such, to affect the build behavior, one needs to register listeners and watch for different events occurring in the build.
The most commonly used listeners are:

BuildServerListener: this is the main place where all server-side events can be watched; all build related events there, like buildStarted or buildFinished, can be useful for build features
AgentLifeCycleListener: this listener can be implemented on the agent side; similarly to the server-side listener, there are build related events which can be useful to build features

Examples of Plugins

Open-source plugins providing build features:

XML Report Processing provides a build feature which processes data on an agent
Commit Status Publisher provides a server-side build feature

Last modified: 15 November 2021