Creating and Editing Build Configurations

Available Options

A build configuration can be one of two major types: a configuration that builds, tests, or deploys a project stored in a VCS, or one that does not require a remote repository (for example, it may employ a 3rd-party REST API to download and process data).

Configurations that check our remote repositories can in turn be created using TeamCity connections or VCS roots.

All available options are displayed in the corresponding drop-down on the Set up your build page.

Use a TeamCity Connection

TeamCity connections store all information required to access an external resource: a VCS hosting, a cloud data storage, a Docker registry, a secrets vault, and so on. Using connections is the most convenient way to build your sources: configure it once and just choose a required repository from the list whenever you add new build configuration or pipeline.

The figure above illustrates a list of existing connections: a GitLab connection, a GitHub connection, few Azure connections, and more. If no project among build configuration parents owns a VCS connection, your only option here will be to create a new one via the Connect new repository menu item.

Use a Repository URL

This option allows you to build configuration in one go using a Git, Subversion, Mercurial, TFS, or Perforce repository (depot) URL. You can use any URL type:

• A regular repository web link: https://github.com/Johndoe/my-sample-app

• An HTTPS clone URL: https://github.com/Johndoe/my-sample-app.git

• An SSH clone URL: git@github.com:Johndoe/my-sample-app.git

To start building a remote repository, follow the steps below.

Use a VCS Root

Every build configuration that processes sources stored in a remote repository does so by leveraging a VCS root. This object stores connection settings required to access a single repository, along with advanced settings: the list of monitored branches, the automatic polling interval, the submodule checkout policy, and more.

If you already have a build configuration or a pipeline that builds, tests, or deploys a required repository, you can reuse a VCS root of that configuration/pipeline. To do this, use either of the following methods:

• Create new configuration — select From an existing root option on the Set up your build page.

• Edit existing configuration — navigate to Build Configuration Settings | Version Control and click Attach VCS root.

  

Reusing existing VCS roots allows you to save time on setting up required authorization and branch settings, and avoid creating duplicate roots.

Configuration Without a Repository

This configuration type doesn’t check out any remote repositories when it runs. Its steps, for example, only execute predefined scripts and send HTTP requests.

You can create a new "unbound: configuration in two ways:

• On the Set up your build page, select Without repository.

• In the classic UI, open the New build configuration page and click the Manually tile.

A VCS root controls the VCS provider connection and repository checkout. Therefore, you can make any build configuration unbound by detaching its VCS root(s). Conversely, attaching a VCS root to a configuration without repositories enables it to check out remote sources. Both actions can be performed in the Version Control section of build configuration settings.

Configuration With Multiple Repositories

Configurations determine which repositories to check out and which branches to track through their attached VCS roots. A configuration can have any number of roots, from none to many.

Typically, a configuration uses a single repository and thus has one VCS root. If you need to build completely separate projects, it’s best to create individual configurations and link them in a build chain if necessary. However, when multiple repositories are related (such as a core product and its plugins), you can attach several VCS roots to the same configuration to build them together. To do this, create a configuration using any of the methods mentioned in this article, then go to the Version Control section of its settings. Here you can create more VCS roots that target required repositories.

The Kotlin DSL snippet below illustrates a configuration with two attached roots.

All VCS roots download sources into the same checkout directory. To avoid file conflicts and keep the folder organized, it’s best to download each repository’s sources into separate subdirectories using root checkout rules. For example, the snippet above places sources in the "MavenRepo" and "GradleRepo" folders within the default checkout directory.

Example: Create a Connection-Based Configuration

In this example, we will add a connection to GitHub and use it to create a new build configuration.

TeamCity supports two GitHub authentication methods: OAuth 2.0 and GitHub App. Both types require minimal customization and take less than a minute to set up. To learn more about both connection types and other VCS provider connections, refer to this article: Configuring Connections.

You can create a connection-based configuration in two ways: create a connection under project settings and select it on the Set up your build page, or do everything from this single page. The tabs below illustrate both approaches.

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:

1. Open project settings and navigate to the General settings tab.

2. Scroll down to the Build configuration templates section and click a required template.

3. Invoke the Actions menu in the top right corner, and click 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. Open project settings and navigate to the General settings tab.

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