TeamCity 8.0 Help

Getting Started

Introduction to Continuous Integration

According to Martin Fowler, "Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily - leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible." To learn more about continuous integration basics, please refer to Martin Fowlers article.

TeamCity and Continuous Integration

TeamCity is a user-friendly continuous integration (CI) server for developers and build engineers that is Installation and free of charge for small and medium teams. With TeamCity you can:

  • Run parallel builds simultaneously on different platforms and environment

  • Optimize the code integration cycle and be sure you never get broken code in the repository

  • Detect hanging builds

  • Review on-the-fly test results reporting with intelligent tests re-ordering

  • Use over 600+ automated server-side inspections for Java, JSP, JavaScript and CSS

  • Run code coverage and duplicates finder for Java and .NET

  • Customize statistics on build duration, success rate, code quality and custom metrics

  • and much more.

Refer to the http://www.jetbrains.com/teamcity/features/index.html page to learn more about major TeamCity features. The complete list of supported platforms and environments can be found Supported Platforms and Environments.

TeamCity Architecture

Unlike some build servers, TeamCity has distributed build grid architecture, which means that TeamCity build system comprises the server and a "farm" of Build Agents which run builds and altogether make up the so-called Build Grid.

Tc scheme

A Build Agent is a piece of software that actually executes a build process. It is installed and configured separately from the TeamCity server. Although you can install an agent on the same computer as the server, we recommend to install it on a different machine for a number of reasons, first of all, for the sake of the server performance.

Build Agents in TeamCity can have different platforms, operating systems and pre-configured environments that you may want to test your software on. Different types of tests can be run under different platforms simultaneously so the developers get faster feedback and more reliable testing results.

While build agents are responsible for actually running builds, TeamCity server's job is to monitor all the connected build agents, distribute queued builds to the agents based on compatibility requirements and report the results. The server itself runs neither builds nor tests.

Since there is more than one participant involved into build process, it may not be clear how the data flows between the server and the agents, what is passed to the agents, how and when TeamCity gets the results, and so on. Let's sort this out by considering a simple case of a build lifecycle in TeamCity.

Installing and Configuring the TeamCity Server Build Agent Build Grid Setting up and Running Additional Build Agents

Build Lifecycle in TeamCity

To demonstrate a build lifecycle in TeamCity, we need to introduce another important term – Version Control System:

Naturally, a VCS, the TeamCity server and a build agent are the three essential components required to create a build. Now, let's take a look at the data flow between them during a simple build lifecycle.

Scheme1

First of all, a build process is initiated by the TeamCity server when certain condition is met, for example, TeamCity has detected new changes in your VCS. In general, there is a number of such conditions which can trigger a build, but right now they are of no interest to us. To launch a build, the TeamCity server tries to select the fastest agent based on the history of similar builds, and of course it selects an agent with an appropriate environment. If there are no idle build agents among the compatible agents, the build is placed into the build queue, where it waits to be assigned to a particular agent. Once the build is assigned to a build agent, the build agent has to get the sources to run on. At this point, TeamCity provides two possible ways for the build agent to get the sources needed for the build:

  • Server-side Checkout

  • Agent-side Checkout

Server-side checkout If the server-side checkout is used, the TeamCity server exports the required sources and passes them to the build agent. Since the build agent itself does not interact with your version control system, you do not need to install a VCS client on agents. However, since sources are exported rather than checked out, no administrative data is stored in the file system and the build agent cannot perform version control operations (like a checkin or label or update). TeamCity optimizes communications with the VCS servers by caching the sources and retrieving from the VCS server only the necessary changes: the TeamCity server sends incremental patches to the agent to update only the files which changed on the agent since the last build.

Agent-side checkout If the agent-side checkout is used, the build agent itself checks out the sources before the build. The agent-side checkout frees more server resources and provides the ability to access version control-specific directories (.svn, CVS); that is, the build script can perform VCS operations (like check-ins into the version control). Note that not all VCS's support agent-side checkout.

When the Build Agent has all the required sources, it starts to execute Build Steps which are parts of the build process itself. Each step is represented by a particular Build Runner, which in its turn is a part of TeamCity that provides integration with a specific build tool (like Ant, Gradle, MSBuild, etc), testing framework (e.g. NUnit), or code analysis engine. Thus, in a single build you can sequentially invoke test tools, code coverage, and, for instance, compile your project.

While the build steps are being executed, the build agent sends all the log messages, test reports, code coverage results and so on to the TeamCity server on the fly, so you can monitor the build process in real time.

After finishing the build, the build agent sends Build Artifacts to the server. These are the files produced by a build, for example, installers, WAR files, reports, log files, etc, when they become available for download.

VCS Checkout Mode Build Artifact

Configuring Your First Build in TeamCity

To configure your first build in TeamCity, perform the following steps:

Start working with TeamCity by creating a project: a project in TeamCity is a collection of your build configurations. It allows you to organize your own projects and adjust security settings: you can assign users different permissions for each project.

Create project

Just click the Create Project link, then specify project's name, Identifier and add an optional description.

When you have created a project, TeamCity suggests to populate it with build configurations:

Create build configuration

A Build Configuration in TeamCity is a number of settings that describe a class of builds of a particular type, or a procedure used to create builds. To configure a build, you need to create a build configuration, so click Create build configuration. Specify general settings for your build configuration, like:

  • The build configuration name, Identifier, description

  • The build number format: each build in TeamCity has a build number, which is a string identifier composed according to the pattern specified here. Configuring General Settings. You can leave the default value here, in which case the build number format will be maintained by TeamCity and will be resolved into a next integer value on each new build start. You can specify the counter in the Build counter field.

  • Artifact paths: if your build produces installers, WAR files, reports, log files, etc. and you want them to be published on the TeamCity server after finishing the build, specify the paths to such artifacts here. Configuring General Settings.

click the VCS Settings button to proceed.

To be able to create a build, TeamCity has to know where the source code resides, thus setting up the VCS parameters is one of the mandatory steps during creating a build configuration in TeamCity. At the Version Control Settings page, TeamCity suggests to create and attach a new VCS Root.

Each build configuration has to have at least one VCS root attached to it. However, if your project resides in several version control systems, you can create as many VCS Roots to it as you need. For example, if you store a part of your project in Perforce, and the rest in Git, you need to create and attach 2 VCS roots - one for Perforce, another for Git. Configuring VCS Roots.

After you have created a VCS root, you can instruct TeamCity to exclude some directories from checkout, or map some paths (copy directories and all their contents) to a location on the build agent different from the default one. This can be done by means of checkout rules:

Checkout rules
Refer to the VCS Checkout Rules for details.

Also, specify whether you want TeamCity to checkout the sources on the agent or server (see checkout). Note, agent-side checkout is VCS Checkout Mode, and in case you want to use it, you need to have version control client installed at least on one agent.

When creating a build configuration, it is important to configure the sequence of build steps to be executed. Each build step is represented by a build runner and provides integration with a specific build or test tool. You can add as many build steps to your build configuration as needed. For example, call a NAnt script before compiling VS solutions. Configuring Build Steps

Basically, these are essential steps required to configure your first build. Now you can launch it by clicking Run in the upper right corner of the TeamCity web UI. However, these steps cover only a small part of TeamCity features. Refer to Creating and Editing Build Configurations sections to learn more about triggering a build, adjusting agent requirements, making your builds dependent on each other, using properties and so on.

Happy building!

Last modified: 20 April 2023