Running Custom Build
A build configuration usually has build triggers configured which automatically start a new build each time the conditions are met, like scheduled time or detection of VCS changes.
Besides triggering a build automatically, TeamCity allows you to run a build manually whenever you need, and customize this build by adding properties, using specific changes, running the build on a specific agent, and so on.
There are several ways of launching a custom build in TeamCity:
Click the ellipsis on the Run button, and specify the options in the Run Custom Build dialog described below.
To run a custom build with specific changes, open the build results page, go to the Changes tab, expand the required change, click the Run build with this change, and proceed with the options in the Run Custom Build dialog.
Use HTTP request or REST API request to TeamCity to trigger a build.
Build triggers can launch builds with custom parameters.
General Options
Select an agent you want to run the build on from the drop-down menu. Note that for each agent in the list, TeamCity displays its current state and estimates when the agent will become idle if it is running a build at the moment. Besides the possibility to run a build on a particular agent from the list, you can also use one of the following options:
Fastest idle agent: default option; if selected, TeamCity will automatically choose an agent to run a build on based on calculated estimates.
Fastest agent in a certain pool: if selected, TeamCity will run a build on an agent from a specified pool
Run a build on <a specified> agent
All enabled compatible agents: Use this option to run a build simultaneously on all agents that are enabled and compatible with the build configuration. This option may be useful in the following cases:
Run a build for agent maintenance purposes (for example, you can create a configuration to check whether agents function properly after an environment upgrade/update).
Run a build on different platforms (for example, you can set up a configuration, and specify for it a number of compatible build agents with different environments installed).
On the General options you can also specify whether
This build will be run as a personal one.
This build will be put at the top of the build queue.
All files in the build checkout directory will be cleaned before this build.
If snapshot dependencies are configured, this option can be applied to snapshot dependencies. In this case, all the builds of the build chain will be forced to use clean checkout.
If the current build configuration uses a Perforce VCS root, you can also run a custom build on shelved files. To do this:
Enable run as a personal build option.
Enter the ID of the changelist that contains the shelved files.
Choose the target Perforce root.
Dependencies
This tab is available only for builds that have dependencies on other builds.
You can enforce rebuilding of all dependencies and select a particular build whose artifacts will be taken. By default, the last 20 builds are displayed.
Note that if you re-run a dependent build, TeamCity will try to rebuild all dependency builds, including failed ones, by default.
By default, dependency builds in the list are grouped by their branches sorted alphabetically. Builds of the same branch are sorted relatively to each other by date. In some cases, you might need to discard branch-based sorting and sort all dependency builds only by their date, to display the newest builds at the top. To do this, click Sort dependencies by date. To return to the default sorting, click Reset all.
Changes
This tab is available only if you have permissions to access VCS roots for the build configuration.
The tab allows you to specify a particular change to be included to the build.
The build will use the change's revision to check out the sources. That is, all the changes up to the selected one will be included into the build.
Note that TeamCity displays only the changes detected earlier for the current build configuration VCS roots. If the VCS root was detached from the build configuration after the change occurred, there is no ability to run the build on such a change. A limited number of changes is displayed. If there is an earlier change in TeamCity that you need to run a build on, you can locate the change in the Change Log and use the Run build with this change action.
Include Changes
The Include changes drop-down menu allows selecting the changes in the VCS roots attached to the configuration to run the build on.
Latest changes at the moment the build is started: TeamCity will automatically include all changes available at the moment.
Last change to include: When you select a change in the drop-down menu, TeamCity runs the build with the selected change and all changes that were made before it. The build run with the changes earlier than the latest available is marked as a history build.
Build Branch
The Build branch drop-down menu, available if you have branches in your build configuration (or in snapshot dependencies of this build configuration), allows choosing a branch to be used for the custom build.
Use Settings
If your project has versioned settings enabled, you can tell TeamCity to run a build:
With the settings defined for the project, either the current settings on the server or the settings from VCS.
With the project settings currently defined on the server.
With the settings loaded from the VCS revision calculated for the build.
If changes are selected in the step above, the revision of the project settings corresponding to the selected changes will be loaded.
To define which settings to take, use one of the corresponding options from the Use settings drop-down menu (the option here will override the project-level setting).
Parameters
This tab allows adding, editing, and deleting new parameters/properties/variables, or redefining their predefined values.
When adding/editing/deleting properties and variables, note the following:
For a predefined property/variable, only the value is editable.
Only newly added properties/variables can be deleted. You cannot delete predefined properties.
Each parameter value must be no longer than 16,000 characters.
Comment and Tags
Add an optional comment as well as one or more tags to the build. You can also add a custom build to favorites by checking the corresponding box in this section.
Promoting Build
Build promotion refers to triggering a custom build with an overridden artifact or snapshot dependency, i.e. manual launching of a build with dependencies configured, but using a build different from the build specified in the dependency.
To promote a build, open the build results page of the dependency build and click Actions | Promote.
For example, your build configuration A is configured to take artifacts from the last successful build of configuration B, but you want to run a build of configuration A using artifacts of a different build of configuration B (not the last successful build), so you promote an earlier build of B.
Build promotion affects only a single run of the dependent build. Once you click Promote, a build of the dependent build configuration which uses the artifacts of the specified build is queued. Any further runs of the dependent build configuration will use artifacts as configured (last successful, last pinned, and so on), unless you use another promotion.
More details are available in the related blog post.