Project Administrator Guide

The following diagram illustrates the basic TeamCity workflow:

1. The TeamCity server detects a change in your repository.

2. The server writes this change to the database.

3. A trigger attached to the build configuration detects the relevant change in the database and initiates a build.

4. The triggered build appears in the build queue.

5. The build is assigned to a free compatible build agent.

6. The agent executes the build steps, described in the build configuration. While executing the steps, the agent reports the build progress to the TeamCity server. It sends all the log messages, test reports, code coverage results on the fly, so you can monitor the build process in real time.

7. After finishing the build, the agent sends build artifacts to the server.

In TeamCity, a building routine consists of the following blocks:

• Build step — an essential building block that executes a predefined set of commands. This can be a single command (like dotnet test or gradle clean build) or a series of operations (such as a custom Python or Bash script). Build steps run fully, with no partial execution.

• Build configuration — a sequence of build steps executed in a specific order. With a configuration, you can:

  • arrange steps in any order you need;

  • temporarily disable individual steps.

  • set conditions for when steps should be executed. If a condition is not met, the corresponding step is skipped. For instance, step #3 could be set to run only if step #2 fails, and step #4 might be configured to execute only on Windows agents.

  Configurations can also be turned into templates making it easy to clone and reuse them without manually configuring each new setup. Once cloned, each copy can be customized independently.

  You can also incorporate configurations from the same or different projects into one unified workflow.

• Project — a collection of independent build configurations. These configurations can be run separately but are grouped under a single project to share common resources: connections, parameters, artifact storages, cloud agent profiles, and so on.

  Each project can be owned by another project for the same benefits: subprojects can access entities owned by their parent projects. The topmost project, called the Root project, is created automatically by TeamCity. This Root project cannot be removed and is ideal for setting up globally accessible parameters, connections, cloud profiles, and other shared resources.

When viewing TeamCity configurations and projects, you can switch between two modes:

View Mode

The view mode for regular day-to-day operations that displays the build history. Users can navigate to individual builds to inspect a build log, view dependent configurations that were triggered along with this build, download produced artifacts, and so on. See the User guide for more information.

Edit Mode

Allows you to modify project or configurations settings: configured build steps, active and disabled build features, build triggers, and more. Depending on user permissions, some of these settings can be unavailable.

To switch between the two modes, use the Settings toggle in the top right corner.

note

For TeamCity users with limited access permissions, the Settings toggle is either completely disabled or allows them to view project/configuration settings in read-only mode.

TeamCity sticks to the selected mode unless you manually toggle it. This means if you view/edit settings of one configuration, navigating to another one will show reveal its settings as well.

For more information on available project and configuration settings, refer to the Creating and Editing Projects and Creating and Editing Build Configurations sections.

A VCS root is a cornerstone of the TeamCity ←→ VCS repository communication. This integral element defines a connection to a VCS provider required to perform a wide range of operations: repository checkout, code sources tagging, communicating build statuses back to VCS, and so on.

VCS roots store the following information:

• Fetch and push URLs that TeamCity uses to pull and push remote files.

• Branch information: the list of repository branches TeamCity should track and which branch is the default (main) one.

• Authentication settings: credentials TeamCity uses to access a repo.

• Checkout settings: specify how remote files should be stored and whether submodules should be checked out along with the main repository.

• Custom changes polling settings that allow you to override the default 60-second interval.

Sections related to VCS roots are available in both project and configuration settings.

However, configurations never own roots. You can "attach" a VCS root to a configuration, but roots are always stored in (owned by) projects. This technique results in the following:

• A VCS root can be attached to multiple configurations, meaning that multiple build configurations can access the same repository with the same auth and checkout settings.

• A single configuration may have multiple VCS roots attached, which allows you to work with different repositories within one configuration.

• Editing VCS roots affects all configurations that use it. When modifying VCS root settings, you have an option to duplicate this root and store updated settings in this new clone, keeping the original root unchanged. This allows you to customize one build configuration but leave other configurations that share this root unaffected.

Although a VCS root is an existential part of any build configuration that works with a remote repository, in many scenarios TeamCity generates roots automatically and does not require that you create them by hand for each new build configuration. See this tutorial for an example.

A build feature is a piece of functionality that can be added to any build configuration to enable additional capabilities. For example, the Commit Status Publisher build feature publishes TeamCity build results to a VCS that stores your code files, and Investigations Auto Assigner identifies users whose latest changes broke the build and automatically tasks them with resolving these issues. Configured build features can be temporarily disabled at any moment without the need to remove them.

Related article: Adding Build Features

TeamCity allows you to set up different building rules for different branches. For example, you might want to build the "production" branch whenever a new change appears, the "development" branch nightly, and ignore the "sandbox" branch. To do this, you need to specify branch specs and filters.

Once your project is set up, TeamCity can receive information about all new changes committed to repository branches included in branch specifications. New changes notifications are received in one of the following ways:

Periodic repository polling

By default, every 60 seconds TeamCity automatically polls all VCS repositories targeted by its projects. The downsides of this approach are:

• Inefficiency — TeamCity keeps constantly polling all repositories, even those that rarely have new changes.

• Performance — If your TeamCity server has a large amount of projects, periodic polling can produce a significant load.

• Delays — After a user committed their change, they can wait up to a minute for this change to show up on TeamCity configuration's Pending changes tab. Users can also use the Actions configuration menu to manually trigger the process:

  

To change the polling interval, navigate to general TeamCity server settings. To override this value for individual configurations, edit the VCS root minimum polling interval setting.

Webhooks

Webhooks allow VCS hosting providers to notify TeamCity about new changes. Compared to the default polling mechanism, this behavior has the following advantages:

• Efficiency — TeamCity server receives change notifications when these changes appear.

• Speed — Change notifications arrive as soon as they are committed.

On the downside, webhooks require manual setup for each repository/project.

Projects that have configured commit hooks still poll their remote repositories as a backup mechanism in case hooks stop working. However, with each successful hook communication, the polling interval automatically doubles. The maximum value to which TeamCity increases this interval is 4 hours, and the minimum interval is 15 minutes. Should scheduled polling reveal a change that did not trigger a commit hook, TeamCity will reset the polling interval to its default value.

Related article: Configuring VCS Post-Commit Hooks

TeamCity users can trigger new builds at any moment via the Run button in the configuration's top right corner. To start new builds automatically, you need to configure triggers.

TeamCity offers various triggers to start new builds based on different events, such as time-based triggers for scheduled builds, change-based triggers for new commits, triggers that launch builds upon the completion of other configurations, and so on.

Related article: Configuring Build Triggers

Artifacts are files produced during a build. These files are available to:

• TeamCity users, who can download them from the Build Results Page.

• Other TeamCity builds, who can import these files using Artifact Dependencies.

To choose which files should be available as build artifacts:

1. Open configuration settings and navigate to the General Settings settings tab.

2. Set up Artifact paths property. You can first run a build that produces required files. Then, you will be able to click the "Select files from the latest build" button and choose files from the drop-down menu instead of manually entering their paths.

Related article: Build Artifacts

Real-life CI/CD pipelines often combine multiple standalone configurations. For example, "Build", "Test", and "Deploy to Staging" configurations (or Jobs) can run independently or in sequence.

TeamCity offers multiple options to create relations between standalone configurations.

Build Chain

A build chain is a collection of classic TeamCity configurations interconnected using snapshot dependencies.

Snapshot dependencies are right-to-left relations. For example, in the "A -> B" chain where configuration "B" has a dependency on configuration "A", "B" cannot run until "A" produces a suitable build first. The criteria for "suitable" builds depends on your setup, see the Suitable Builds section for more information. At the same time, "A" can run independently without triggering new "B" builds.

For mission-critical scenarios, you can set up dependent configurations to always force fresh upstream configuration builds, even if there were no recent changes to the project.

Finish Build Triggers

Finish build triggers establish left-to-right relations. For example, you can create a similar "A -> B" sequence similar to a build chain, but with one key difference: "B" can run independently, while each new "A" build automatically triggers a new "B" build.

Finish build triggers offer a simple but inflexible way to trigger downstream builds and can often be replaced or complemented by snapshot dependencies.

Artifact Dependencies

Artifact dependencies allow configurations to import files produced during other configurations' builds. For example, a "Delivery" configuration can deploy files (Docker images, NuGet packages, HTML documentation pages, and so on) produced by a "Build" configuration to a designated resource.

Artifact dependencies don’t create explicit links between configurations: both can run independently without triggering each other’s builds. If you use artifact dependencies without corresponding snapshot dependencies, a dependent build has no ability to ensure a suitable source of artifacts (an upstream configuration build) exists. For that reason, you may want to set up artifact dependencies to target pinned/tagged builds. This setup can exhibit more control on your building routine.

Deployment is typically the final stage of a CI/CD routine that delivers artifacts produced by a build to an external location. Depending on your scenario and needs, you can perform this action as a final build step, or a standalone deployment configuration.

Ways to deploy artifacts in TeamCity:

• Via a command line, using any general runner like Command Line or PowerShell. This is the most straightforward approach. Just add a build step, select any such runner, and enter commands as if in a regular terminal. The benefits you get from TeamCity in this case are flexible automation, synchronization with the previous build stages, and a convenient view of build results in the TeamCity UI.
  This way, you can also update distribution files in a third-party storage, like Amazon S3.

• Using a specific runner for your platform. For example, if you build .NET projects, the best way to deploy them is via our .NET runner. It supports all the relevant .NET commands such as pack or publish and offers a variety of other features. Other runners are listed under this section.

• Using a deployer. TeamCity offers several build runners dedicated to deployment: SMB Upload, FTP Upload, SSH Upload, and SSH Exec. They can upload build artifacts via different protocols and let you configure this upload process in the TeamCity UI.

• Using the AWS CodeDeploy runner to deploy applications to AWS EC2 and on-premises instances. To use this runner, you need to download and install our AWS CodeDeploy plugin as described here. See the related blog posts.

tip

If you deploy products by means of third-party services, TeamCity allows detaching builds from agents before starting the external deployment operations. This helps utilize agents more optimally.

This method requires some advanced configuration, so we suggest trying it only after you feel comfortable configuring builds and agents in TeamCity.

Every build problem or test failure in TeamCity can be investigated as a separate incident. See the following article for more information: Working with Build and Test Failures.

Build problems and failed tests can be muted to allow builds finish successfully even when they encounter these problems. Note users with the default project developer role cannot mute issues, only project administrators are allowed to do this.

To automatically assign investigations to users whose changes likely failed a build, configure the Investigations Auto Assigner build feature.

The Configure and Run Your First Build tutorial walks you through the main stages of setting up a TeamCity project: establishing a VCS connection, setting up build actions, configuring additional features, assigning users to this project, and more.