Creating and Editing Build Configurations

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:

   • manually

   • pointing to a repository URL

   • pointing to a repository in GitHub.com, GitLab CE/EE, Bitbucket Cloud, Azure DevOps Services, and JetBrains Space

   • based on a build configuration template

After build configurations are created, you can:

• change their order

• edit their settings

• control them via the Actions menu

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

   • Create/edit VCS roots and specify VCS-specific 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:

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.

   

3. Click Actions | Create build configuration from this 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.

   

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

• 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:

• Pause/activate a build configuration.

• Copy/move/delete a build configuration.

• Attach a build configuration to a template.

• Extract a template from a build configuration.

• Extract a meta-runner from a build configuration.

• Attach a history to a build configuration.