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 environment 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 of the server and a "farm" of Build Agents which run builds and altogether make up the so-called Build Grid.

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

TeamCity's Build Agents 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 server and agent, what is passed to agents, how and when TeamCity gets the results, and so on. Let's sort this out by considering a simple case of 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 build lifecycle in TeamCity we need to introduce another important term – Version Control System:

Naturally, VCS, TeamCity server and build agent are 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.

First of all, a build process is initiated by 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 TeamCity server tries to select the fastest agent based on the history of similar builds, and of course it selects an agent with appropriate environment. If there's no idle build agents among the compatible agents, the build is placed to 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 how the build agent can get sources needed for the build:

• Server-side Checkout

• Agent-side Checkout

Server-side checkout If server-side checkout is used, TeamCity server exports the required sources and passes them to the build agent. Since the build agent itself doesn't interact with your version control system, you don't need to install VCS client on agents. However, since sources are exported rather than checked out, no administrative data is stored in the file system and build agent cannot perform version control operations (like check in 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: TeamCity server sends to the agent incremental patches to update on the agent only the files changed since the last build.

Agent-side checkout If agent-side checkout is used, the build agent itself checks out the sources before the build. 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 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, 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, build agent sends to the server Build Artifacts, 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 following simple steps:

Start working with TeamCity by creating a project: a project 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.

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

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

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 build configuration, so click the add a build configuration link. Specify general settings for your build configuration, like:

• Build configuration name

• 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 build number format will be maintained by TeamCity and will be resolved into a next integer value on each new build start. The counter you can specify in the Build counter field.

• Atrifact 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 build, specify here paths to such artifacts. Configuring General Settings.

If needed, specify Configuring General Settings and 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 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 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 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 build agent different from the default. This can be done by means of checkout rules:

Also, specify whether you want TeamCity to checkout the sources on 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 dependant on each other, using properties and so on.

Happy building!