Creating and Editing Build Configurations
This section contains articles on how to create and configure build configurations via the TeamCity UI.
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 Settings page.
![Create a build configuration Create a build configuration](https://resources.jetbrains.com/help/img/teamcity/2023.09/create-build-configuration-button.png)
It is recommended to have a separate build configuration for each sequence of builds (that is performing a specified task in a dedicated environment). This allows for proper features functioning, like detection of new problems/failed tests, first failed in/fixed in tests status, automatically removed investigations, and so on.
To tackle an increased number of build configurations you can use build configuration templates and project-level parameters.
This video tutorial illustrates how to work with a build configuration in TeamCity and gives a few extra tips:
Where to Create Build Configuration
To find the build configuration creation wizard:
Go to Administration | Projects and open the required project.
Alternatively, open the project using the Projects pop-up menu and click Edit Project Settings.
The Project Settings page will open.On the Project Settings page, click Create build configuration under the Build Configurations section.
Follow the instructions specific to your preferred method:
pointing to a repository in GitHub.com, GitLab CE/EE, Bitbucket Cloud, Azure DevOps Services, and JetBrains Space
based on a build configuration template
![Create a build configuration from a repository URL Create a build configuration from a repository URL](https://resources.jetbrains.com/help/img/teamcity/2023.09/create-build-configuration.png)
After build configurations are created, you can:
control them via the Actions menu
Creating Build Configuration from URL
In the build configuration creation wizard:
Click From a repository URL.
Enter your VCS repository URL and, if authentication is required, VCS credentials (username and password/token).
Click Create.
TeamCity will suggest the build configuration name and will configure the rest of the settings for you:
It will determine the type of the VCS repository and create a VCS root. For a Git repository, it will autodetect the default branch. You have an option to change it now or later, in the VCS root settings. You can also change the branch specification: by default, TeamCity monitors all branches of the repository, but you can choose what exact branches to monitor by entering custom rules.
It will attempt to autodetect build steps: Ant, NAnt, Gradle, Maven, MSBuild, Visual Studio solution files, PowerShell, Xcode project files, Rake, and IntelliJ IDEA projects. You can then always add and edit them manually.
Next, TeamCity will display suggestion icons with prompts to create build triggers, failure conditions, and build features. Depending on the build configuration settings, it may suggest some additional configuration options.
After the build configuration is created, you can run a build and/or tweak the settings.
Creating Build Configuration Pointing to Specific VCS
In the build configuration creation wizard:
Click the button respective to your VCS: from GitHub.com, GitLab CE/EE, Bitbucket Cloud, Azure DevOps Services, or JetBrains Space.
Note that to be able to access the selected VCS, TeamCity needs to always have the connection parameters at its disposal. You can configure the connection preset in advance and select the target VCS server in the wizard, or let TeamCity redirect you to the Connections page right from the wizard. The connections settings of supported VCS providers are described here.Verify the connection to the VCS.
TeamCity will propose the build configuration name. You can change it if needed.
For a Git repository, it will also autodetect the default branch. You have an option to change it now or later, in the VCS root settings. You can also change the branch specification: by default, TeamCity monitors all branches of the repository, but you can choose what exact branches to monitor by entering custom rules.
Click Proceed.TeamCity will add a VCS build trigger and attempt to autodetect build steps: Ant, NAnt, Gradle, Maven, MSBuild, Visual Studio solution files, PowerShell, Xcode project files, Rake, and IntelliJ IDEA projects. On the Auto-detected Build Steps page, select the step(s) to use in your build configuration. Click Use selected. You can then always add or edit steps manually.
Depending on the build configuration settings, TeamCity can suggest some additional configuration options. Review the suggested settingsand configure the required ones.
The build configuration is created. Click Run to start its first build.
Creating Build Configuration Manually
In the build configuration creation wizard:
Click Manually
In the Create Build Configuration dialog, specify the name, ID and (optionally) description for the build configuration, click Create.
Proceed with creating other settings:
On the Build Steps page, configure build steps discovered by the automatic detection. To create them manually by selecting a desired build runner from the drop-down menu. Click Save. You can add as many build steps as you need within one build configuration. Note that they will be executed sequentially. In the end, the build gets the merged status and the output goes into the same build log. If some step fails, the rest is executed or not, depending on their step execution policy.
Additionally, configure build triggering options, dependencies, properties and variables, and agent requirements.
Creating Build Configuration Template
Creating a new build configuration template is similar to creating a new configuration:
On the Administration | Projects page, select the target project in the list.
Alternatively, open the project using the Projects pop-up menu and click Edit Project Settings.
The Project Settings page opens.On the Project Settings page, click Create template under the Build Configuration Templates section.
Proceed with configuring general settings, VCS settings, and build steps.
Alternatively, you can create a build configuration template from an existing build configuration:
Open the existing build configuration settings page, click Actions in the upper right corner of the screen, and select the Extract Template option.
Specify the required settings and click Create.
Creating Build Configuration from Template
You can create a templated build configuration in two ways: from the template settings page, or by creating a regular configuration and choosing a template it should utilize.
Option #1:
Navigate to Administration | Project and select a project that owns a template.
Click a required template under the Build configuration templates section.
Click Actions | Create build configuration from this template....
Specify the required settings for the new configuration. Do not click any tiles other than Manually; otherwise, you will create a new configuration where the selected template is not used.
Option #2:
Navigate to Administration | Project and select a project that owns a template.
Click Create build configuration under the Build Configurations section.
Click the Manually tile and choose the required template in the Based on template drop-down menu.
Option #2 is helpful when the Build configuration templates section does not show the required template since it is owned by another (sub)project.
Ordering Build Configurations
You can view all build configurations of a project on the Project Overview page. By default, they are listed in the alphabetical order, but administrators can customize this order.
Build Configuration Settings
Build configuration settings include:
Version control settings, defining how the source code is retrieved from VCS, where it is checked out to, and so on
Build steps, that are sequentially run actions: for example, running msbuild, a script, or unit tests
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 snapshot dependencies, TeamCity will run all dependent builds on the sources taken at the moment the build they depend on starts
for artifact dependencies, 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.
Configuring Settings
When you select a build configuration from the list of build configurations, TeamCity displays the Build Configuration Home page where you can preview its recent build results. To access the build configuration's settings, click Edit Configuration Settings in the upper right corner of the screen.
Different build configuration settings are described in the respective articles inside this section.
Permissions to Edit Build Configuration
While only users with Project Administrator's permissions can change project and build configuration settings, there are several ways how contributors to the source code can also affect the build settings and environment.
The default Project Developer role grants users two permissions:
Customize build parameters allows changing the values of build configuration parameters thus potentially affecting how the source code is executed.
Change build source code with a custom patch allows running a custom build based on a user's local sources, not yet committed to the repository.
Besides, all the users who author the source code or/and can write to the repository with project settings stored in Kotlin DSL, could potentially execute their arbitrary code on common build agents.
We recommend considering this aspect when granting users the permissions mentioned above or writing access to the projects' repositories. If necessary, you can adjust the set of permissions granted to each role.
Actions in Build Configuration Settings
Use the Actions menu, located in the upper right corner of the settings screen, to: