Creating and Editing Build Configurations

Build configurations and pipelines represent actual CI/CD routines. A build configuration stores a sequence of build steps (basic operations to be performed during a build run), and settings required to execute these steps. These settings include:

parameters that allow you to quickly alter the configuration behavior;
triggers that allow TeamCity to automatically start new builds when certain conditions are met;
build features that extend the configuration's functionality;
agent requirements that allow you to run configuration builds on specific build agents;
and so on.

It is recommended to have a separate build configuration or a pipeline 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.

Build Configurations vs Pipelines

Before we dive into creating configurations, it’s important to understand the differences between build configurations and pipelines and when to use each. Note that once created, you cannot convert a build configuration into a pipeline or a job, and vice versa.

Parents

Both build configurations and pipelines are owned by TeamCity projects. Each project can have an unlimited number of configurations and pipelines.

Children

A build directly owns its build steps.
A pipeline owns jobs, which in turn own regular build steps.

Supported VCS types

Classic TeamCity build configurations support Git, Subversion, Mercurial, TFS, and Perforce, with integrations for major VCS providers like GitHub, GitLab, Bitbucket, Azure, and others.
TeamCity Pipelines offer built-in integrations with GitHub, GitLab, and Bitbucket Cloud. Other Git repositories can be connected via direct URLs. Subversion, Mercurial, TFS, and Perforce are not currently supported.

Execution mode

Pipelines always run from start to finish, executing all jobs unless interrupted by errors like compilation failures or connection issues.
Build configurations support conditional step execution. For example, you can add a step that runs only if a previous one fails.

Dependencies

Currently, pipelines support dependencies only between jobs within the same pipeline and cannot be linked into a larger sequence.
Build configurations can form build chains across different TeamCity projects.

Configuration as code

Both pipelines and build configurations can store their settings as code, right next to your project source code. Both entities support branched settings, meaning each repository branch can have its own configuration file.

Build configurations store their settings in XML or Kotlin DSL format. You cannot edit these files from the TeamCity UI.
Pipelines store their settings in YAML which can be edited directly in TeamCity.

Kotlin DSL support is planned for future pipeline versions. However, there are no current plans to add YAML support for build configurations.

Limitations

Build configurations are core TeamCity components, offering extensive features and customization options.
Introduced in TeamCity 2025.07, Pipelines focus on providing the most intuitive way to design CI/CD workflows. However, they currently lack some of the functionality available in build configurations. For example, they do not support the majority of build steps and have no additional build features.

In summary, while both pipelines and build configurations are owned by projects, they serve different needs. Pipelines are ideal for simpler CI/CD workflows in smaller projects (typically up to 10–15 builds). Choose build configurations instead if:

Your project involves more complex workflows than 10–15 sequential builds.
You are an experienced user who needs advanced features (such as Build Approval) not yet available in pipelines.
You require fine-grained control over which build chain configurations run, when, and how.

Create Build Configurations in TeamCity UI

Creating new build configurations shares a lot of similarities with creating projects: both can utilize connections and rely on VCS roots to access remote repositories.

New Projects

When you create a new TeamCity project from a repository URL or via a configured connection, TeamCity guides you through setting up both the project and its build configuration. See the links above for more details.

Add Configurations to an Existing Project

If a parent project already exists, you can add its child configurations as follows:

Use the + button in the sidebar...
...or click Create build configuration from the General tab of project settings.
You will be presented with the same set of options as for creating projects:
- From a repository URL — adds a new configuration using a repository link. See this link for more information.
- From a configured connection — available if this project or any of its parent projects has a VCS provider connection. Faster than the first option since authentication settings are inherited from the underlying connection. See this link for more information.
- Manually — creates a completely blank build configuration that does not target any remote repository. This option allows you to choose a template attached to the configuration.
If you created an empty build configuration (using the Manually option), you will need to attach an existing VCS root or create a new one to check out remote repositories. A configuration can include multiple VCS roots to handle repositories from the same or different providers.
Attach or Create VCS Root
1. Go to Administration and click the project you want to configure.
2. From the project's General Settings page, click the relevant build under Build Configurations
3. Select Version Control Settings from the sidebar.
4. Click Attach VCS root.
5. If there is at least one existing VCS root available, TeamCity offers a choice between the following actions:
  - Attach existing VCS root — select the VCS root to attach and then complete the Update Checkout Rules form.
  - Create new VCS root — configure the new VCS root, following the guidelines in Configuring VCS Roots.
  If there is no existing VCS root available, TeamCity jumps straight to the Create new VCS root page.
See the following articles for more information:
- Configuring VCS Settings
- Configuring VCS Roots

Create New Projects in Kotlin DSL

The following Kotlin code creates a new build configuration that utilizes the target VCS root to interact with a VCS hosting provider:

object RunTests: BuildType({
  id("RunTests")
  name = "Run unit tests"
  description = "Runs all unit tests of the project"

  vcs {
    root(MyProjectVCSRoot)
  }

  steps {
    // Add build steps
  }

  triggers {
    // Add triggers
  }
})

See these articles for more information:

Create Build Configuration in REST API

The following request creates a new empty TeamCity build configuration owned by the specific parent project.

export TEAMCITY_SERVER_URL="<Your TeamCity Server URL>"

curl --location $TEAMCITY_SERVER_URL'/app/rest/projects/<parent_project_locator>/buildTypes' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Your TeamCity Access Token>' \
--data '{
    "name": "New Build Configuration from REST"
}'

See the following articles for more information:

Build Configuration Templates

Templates allow you to quickly spawn multiple configurations with identical settings. After a configuration is created, you can override its settings.

You can create build configuration templates manually or extract them from existing configurations.

Create a template manually

Creating templates is identical to creating build configurations via the Manually tile.

Open project settings and navigate to the General settings tab.
Scroll down to the Build Configuration Templates section and click Create template.
Enter the template name and description, and click Create.
Specify settings that should present in every configuration spawned from this template:
- Build steps
- Build parameters
- Triggers, and more.

Extract a template from a configuration

If you already have a build configuration that you want to use as reference, you can extract a template from it.

Open build configuration settings.
Open the Actions menu in the top right corner and click Extract template....
Enter the configuration name and click Extract. You can keep the template ID as its autogenerated value.
The source configuration will be the first to use the new template. To keep it independent, click Detach. Otherwise, any changes to the template will apply to this and all other configurations based on it.

Create a Build Configuration From a 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:

Open project settings and navigate to the General settings tab.
Scroll down to the Build configuration templates section and click a required template.
Invoke the Actions menu in the top right corner, and click 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:

Open project settings and navigate to the General settings tab.
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. This menu is available if this project or any of its parent projects own at least one build configuration template.

Option #2 is helpful when the Build configuration templates section does not show the required template since it is owned by another (sub)project.

Re-Arrange 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:

General settings
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.

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: 03 June 2025