TeamCity Cloud 2023.11 Help

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

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:

  1. 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.

  2. On the Project Settings page, click Create build configuration under the Build Configurations section.

  3. Follow the instructions specific to your preferred method:

Create a build configuration from a repository URL

After build configurations are created, you can:

Creating Build Configuration from URL

In the build configuration creation wizard:

  1. Click From a repository URL.

  2. Enter your VCS repository URL and, if authentication is required, VCS credentials (username and password/token).

  3. 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:

  1. 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.

  2. Verify the connection to the VCS.

  3. 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.

  4. 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 settings suggestedSettings.PNG and 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:

  1. Click Manually

  2. In the Create Build Configuration dialog, specify the name, ID and (optionally) description for the build configuration, click Create.

  3. Proceed with creating other settings:

Creating Build Configuration Template

Creating a new build configuration template is similar to creating a new configuration:

  1. 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.

  2. On the Project Settings page, click Create template under the Build Configuration Templates section.

  3. Proceed with configuring general settings, VCS settings, and build steps.

Alternatively, you can create a build configuration template from an existing build configuration:

  1. Open the existing build configuration settings page, click Actions in the upper right corner of the screen, and select the Extract Template option.

  2. 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:

  1. Navigate to Administration | Project and select a project that owns a template.

  2. Click a required template under the Build configuration templates section.

    Choose the required template
  3. Click Actions | Create build configuration from this template....

    Create new configuration from a template
  4. 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:

  1. Navigate to Administration | Project and select a project that owns a template.

  2. Click Create build configuration under the Build Configurations section.

    Create a regular configuration
  3. Click the Manually tile and choose the required template in the Based on template drop-down menu.

    Create a regular configuration

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:

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:

Last modified: 04 March 2024