Running Custom Build
A build configuration typically uses build triggers to start new builds on a required schedule or whenever TeamCity detects a new change in a source code.
In addition to these automatically triggered builds, TeamCity allows you to run builds manually and, if needed, customize their settings: add new or modify existing properties, choose specific changes, schedule a build, choose which agent should run it, and so on.
TeamCity provides multiple options to run custom builds:
Click the ellipsis button next to the Run button and specify optional settings in the Run Custom Build dialog (see this section for more information).
To run a custom build with specific changes, open the build results page and switch to the Changes tab. Expand the required change, click the Run build with this change button, and specify required options.
Set up build triggers to launch builds with custom parameters.
General Options
The General tab displays the most basic and frequently used settings.
Agent
This setting allows you to choose an agent that should run your build. The following options are available:
<the fastest idle agent> (default option) — if selected, TeamCity will automatically choose an agent to run a build.
Select a specific TeamCity agent from a list. TeamCity displays a designated agent's current state and (if it is already running a build) estimates when it will become idle.
<the fastest idle agent in the N pool> — TeamCity will run a build on an agent from a specified pool.
if cloud integration is configured, you can run a build on an agent spawned from a certain cloud image. If no cloud agents of this type are available, TeamCity will attempt to start a new one.
<All enabled compatible agents> — run a build simultaneously on all agents that are enabled and compatible with the build configuration. Use this option to:
Run a build for agent maintenance purposes (for example, you can create a configuration to check whether agents function correctly after an environment upgrade/update).
Run a build on different platforms (for example, you can set up a configuration and specify a number of compatible build agents with different environments installed.
Date & Time
Leave the As soon as possible option to place a new build to a regular queue immediately after you click Run Build.
To schedule a build to the specific date & time, switch to the At specific date and time option. Scheduled builds remain at the end of a build queue until their scheduled date and time.
Build Options
run as a personal build — allows you to run personal builds.
put the build to the queue top — places this new build to the top of the current build queue. Since your newly started build can have no immediately ready compatible agents, it can move down the queue as it waits for one. If this happens, click the Move to top icon on the build configuration page, or navigate to the Build Results Page page and click Actions | Move to top.
delete all files in the checkout directory before the build — specifies whether TeamCity should clear the build checkout directory.
If snapshot dependencies are configured, this option can be applied to snapshot dependencies. In this case, all the builds of the build chain will use a clean checkout.
Perforce-Specific Settings
If the current build configuration uses a Perforce VCS root, you can also run a custom build on shelved files. To do this:
Tick 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.
The Dependencies tab allows you to rebuild all dependencies and select a particular build whose artifacts this new build should use. By default, TeamCity shows the last 20 builds. To increase the number of available recent builds, add the teamcity.runCustomBuild.buildsLimit=<your value> internal property.
If you re-run a dependent build, TeamCity will try to rebuild all dependency builds, including those that previously failed.
Dependency builds in the list are initially grouped by their alphabetically sorted branches. Builds of the same branch are sorted by the build date. To discard branch-based sorting and sort all dependency builds only by their dates, click Sort dependencies by date. This allows you to view the most recent builds first. To restore the default sorting, click Reset all.
Changes
This tab is available only if your TeamCity user has permission to access VCS roots for the build configuration.
The Changes tab allows you to select a change to be included to the build. TeamCity will use the change's revision to check out the sources and include all changes up to the selected one in this new build.
Note that if a corresponding VCS root was detached from the build configuration, TeamCity is unable to retrieve newest commits and displays only a limited number of changes. To run a build with an older chage, locate the required commit in the Change Log and use the Run build with this change action.
Include Changes
The Include changes drop-down menu allows you to choose which changes in the VCS roots attached to the configuration should be included in this new build.
Latest changes at the moment the build is started: TeamCity will automatically include all latest changes available at the moment.
Last change to include: Choose a required change to ignore all later commits. TeamCity marks builds that ignore newest changes as history builds.
Build Branch
The Build branch drop-down menu is available if this build configuration (or its snapshot dependency configuration) has branches. Allows you to choose a branch for the custom build.
Use Settings
If a project stores its settings in a VCS, this tab allows you to choose which settings should be used for this new build:
Settings currently defined on the TeamCity server
Settings loaded from the VCS revision calculated for this build.
The default behavior depends on the currently selected Project Settings | Versioned Settings page setting (see this section for more information: Defining Settings to Apply to Builds).
If you selected specific changes revision, TeamCity will also load a corresponding revision of the project settings.
Parameters
This tab allows you to adding, edit, and delete parameters/properties/variables, as well as override initial values of predefined parameters.
The following limitations apply:
Predefined properties and variables do not allow you to edit their names (only values are editable).
You can delete only newly added properties and variables. Predefined properties cannot be removed.
Parameter values must not exceed 16,000 characters.
Comment and Tags
This tab allows you to add optional comments and tags to your custom builds. You can also add a custom build to favorites by checking the corresponding option in this section.
Promoting Build
Promoted builds are custom builds with an overridden artifact or snapshot dependencies. Such builds utilize different dependency builds compared to those they would use by default.
For example, a build configuration A retrieves artifacts from a build configuration B. Normally, running a new A build utilizes the last successful B build. If you want A to use an older B build, this earlier B build needs to be promoted.
To promote a build, open the build results page of the dependency build and click Actions | Promote. Promotion has a one-time effect: after the current run, build configurations revert back to their default dependency logic (last successful or last pinned build).
See the following blog post for more information.