Terms and Concepts

TeamCity Object Hierarchy

Projects are the topmost objects of the TeamCity hierarchy, and Root project is the main default project that contains all your custom projects and their subprojects. Each project serves for storing logically related build configurations and defining their common settings and parameters. Most often, a TeamCity project corresponds to a single software product or its specific version.

Projects can be configured manually or automatically, from a VCS repository. The settings of each repository used in a project are stored in a dedicated preset called VCS root. Besides VCS roots, a project contains other settings shared between its nested subprojects and build configurations: cloud profile connections, common parameters, clean-up rules, and many others.

Example of a simple object hierarchy in TeamCity:

A build configuration serves as a blueprint for running a certain job, or a build, based on the project's source code: either it is a compilation, testing, deployment — or all these stages one by one. A single build configuration can define settings that are used to run, for example, a nightly build or integration tests.
In certain cases, you may need to create multiple build configurations that differ only in few details. For this purpose, you can compose a build configuration template and use it to generate as many similar build configurations as needed. One of the popular use cases for using templates is testing and deploying software on different operating systems.

tip

In TeamCity terms, it is considered that a build configuration belongs to its parent project and that each running build that uses this configuration as a blueprint belongs to this build configuration. In certain contexts, you will notice that the terms build and build configuration are used interchangeably in the documentation. For example, if we describe two related builds from different configurations, we can perceive each build both as a single running job and as a carrier of its build configuration settings.

Each build configuration can have build features and build steps. A build feature is a piece of extra functionality available to a build: it could be a performance monitor, a reporting tool, or a support for pull requests. Some features are built in TeamCity and some can be obtained by installing external plugins. A build step is a logical stage of a build that is performed by a certain build runner. TeamCity offers a wide range of different runners: from testing tools to Docker integration.

Another important setting included into a build configuration is a trigger. There are multiple types of triggers in TeamCity. Their common purpose is to run a build automatically when a preconfigured condition is satisfied, thus establishing automatic continuous integration of a software product.

TeamCity offers all these granular objects so you can configure a build process as flexibly as possible. However, they would make more sense if you have the means to interconnect them with each other. For this purpose, TeamCity provides two types of dependencies between build configurations (that is between their builds):

• artifact dependency — for sending artifacts produced by one build to another build; an example of an artifact is a .jar application that is compiled by one build configuration and deployed by another.

• snapshot dependency — for assigning multiple builds to the same source revision (commit) so the same project files are used on all the building stages.

By connecting builds from different configurations or even projects with dependencies, you can create a flexible build chain. The TeamCity product itself is built with a complex chain of builds. It allows us to compile and test different software modules and deploy the resulting distribution files to the web.

Example of a build chain in TeamCity:

TeamCity Build Environment

The TeamCity server stores all the objects' settings, manages the build queue, monitors the state of running builds, and performs many other tasks. You can install as many additional secondary servers as you need to ensure high availability and scalability of your setup.
You can host the server on your own machine or get a TeamCity Cloud subscription so your server is automatically launched and maintained in the cloud.

A different piece of software is used for actually running builds — a build agent. By default, you get three build agents with your TeamCity server but you can get more if required. A build agent software can be installed on a different machine or alongside the server.

tip

Check out the basic CI workflow in TeamCity to see an example of a simple build run.

Learn More

To learn more about TeamCity, explore this Help further:

• The current Concepts section lists the main TeamCity objects and terms. Use it as a reference to learn about unfamiliar notions.

• To properly install and configure your setup, refer to Supported Platforms and Environments and Installation.

• If you are using TeamCity only for managing and viewing builds, make sure to read this section.

• If you have a Project Administrator or Server Administrator access, use the TeamCity Configuration and Maintenance section to learn how to configure projects or how to use the Administration panel and maintain the server. This section also contains information on licensing and configuration as code in TeamCity.

• Available TeamCity add-ins are described here.

• Under Extending TeamCity, advanced users can learn how to run build scripts for interacting with TeamCity, how to use TeamCity REST API, and more.

• If none of these sections answer your questions, try looking into Troubleshooting and How-to.

Additional information resources:

• Key features of TeamCity

• CI/CD Guide

• How to write custom TeamCity plugins

• TeamCity Roadmap