Build Configuration

A Build Configuration is a collection of settings used to start a build and group the sequence of the builds in the UI. Examples of build configurations are distribution, integration tests, prepare release distribution, "nightly" build.

A build configuration belongs to a project and contains builds. You can explore details of a build configuration on its home page and modify its settings on the editing page.

To tackle an increased number of build configurations you can use Build Configuration Templates and project-level parameters.

Build Configuration Settings

Build configuration settings include:

• General settings

• Version control settings, defining how the source code is retrieved from VCS, where it is checked out to, etc.

• Build steps, i.e. actions that are run sequentially: e.g. running msbuild, a script, unit tests, etc.

• Triggers, which are rules defining when to start a new build

• Failure conditions specifying when a build will be marked as failed

• Additional build features

• Dependencies:

  • for , TeamCity will run all dependent builds on the sources taken at the moment the build they depend on starts

  • For , before a build is started, all artifacts this build depends on will be downloaded and placed in their configured target locations and then will be used by the build.

• Parameters which allow sharing settings

• Agent requirements specifying whether a build configuration can run on a particular build agent.

Build Configuration Types

The following build configuration types exist in TeamCity: - regular build configuration, defining actions and rules to apply to the source code. All the settings above are applicable. - deployment build configuration, which deploys artifacts of other builds to some environment (since TeamCity 2017.2) - composite build configuration, which aggregates results from several other builds combined by snapshot dependencies and presents them in a single place (since TeamCity 2017.2)

Build Configuration State

A build configuration is characterized by its state visible in the UI which can be paused or active. By default, when created all configurations are active and can be paused manually as described below or automatically if the project is archived.

If a build configuration is paused, its automatic build triggers are disabled until the configuration is activated. Still, you can start a build of a paused configuration manually or automatically as a part of a Build Chain. Besides, information on paused build configurations is not displayed on the Changes page.

Since TeamCity 10.0, it is possible to manually pause all or selected build configurations for a project.

Pausing / Activating several build configurations of a project

To pause several build configurations of a project, do the following:

On the Project Settings page:

1. Click the Actions button, select the Pause/Activate triggers.

2. In the dialog that opens select the box next to the project to pause all its build configurations or check the boxes of the configurations selectively: the checked build configurations will be paused.

3. Add an optional comment

4. To remove the builds of the paused configurations from the build queue en masse, check the Cancel already queued builds if build configuration is paused box.

5. Click Apply.

To activate several build configurations of a project, do the following:

On the Project Settings page:

1. Click the Actions button, select the Pause/Activate triggers.

2. In the dialog that opens clear the box next to the project to activate all its build configurations or clear the boxes of the configurations selectively: the unselected build configurations will be activated.

3. Add an optional comment

4. Click Apply.

Pausing / Activating a single build configuration

To pause or activate an individual build configuration, do one of the following:

• On the Build Configuration Settings or Home Page page: click the Actions button, select the Pause triggers..., add your comment (optional) and click Pause. For a paused configuration, click the Activate button at the top of the settings page. To remove the builds of the paused configuration from the build queue, check the Cancel already queued builds box.

Build Configuration Status

In general, a build configuration status reflects the status of its last finished build.

Personal builds do not affect the build configuration status.

You can view the status of all build configurations for all/particular project on the Projects Overview page or Project Home Page, when the details are collapsed.

Build configuration status icons:

Icon	Description
	The last build on default branch executed successfully.
	The last build on default branch executed with errors or one of the currently running builds is failing. The build configuration status will change to "failed" when there's at least one currently running and failing build, even if the last finished build was successful.
	Indicates that someone has started investigating the problem, or already fixed it. (see Investigating and Muting Build Problems).
no icon	There were no finished builds for this configuration, the status is unknown. If none of the build configurations in a project have finished builds, the is displayed next to a project name
	The build configuration is paused; no builds are triggered for it. Click on the link next to the status to view by whom it was paused, and activate configuration if needed.

Status Display for Set of Build Configurations

It is possible to filter out the build configurations whose status you want to be displayed in TeamCity or externally.

To display the status of selected build configurations in TeamCity:

• configure visible projects on the Projects Overview page to display the status of build configurations belonging to these projects only

• implement a custom Java plugin for TeamCity to make the page available as a part of the TeamCity web application

To display the status for a set of build configurations externally (e.g. on your company's website, wiki, Confluence or any other web page), you can:

• use the external status widget

• use the build status icon

• use any of the available visualization plugins

• implement a separate page or application which will get the build configuration status via the TeamCity REST API