Basic Concepts

This section gives a list of basic terms and their definitions, that will help you successfully work with TeamCity. The list is arranged in alphabetical order.

• account

• administrator

• Agent-Requirement

• Agent-Working-Directory

• buildArtifact

• auth

• Build-Agent

• Build-Configuration

• Build-Configuration-States

• Build-Counter

• distributedBuilds

• Build-History

• Build-Log

• Build-Numbering

• Build-Queue

• buildRunner

• buildStates

• buildTrigger

• Build-Working-Directory

• Change

• changeStates

• Clean-Sources

• Clean-Up-Policy

• Code-Coverage

• Code-Duplicates

• Code-Inspection

• Continuous-Integration

• Delayed-Commit

• dependentBuilds

• guest

• Licensing-Policy

• notifications

• notificationCondition

• notificationRules

• notifier

• Personal-Build

• Pinned-Build

• Project

• vcsRoots

• Responsibility

• Remote-Run

• Roles

• dd

• user

• Version-Control-System

• VCS-Checkout-Subdirectory

Account

There are three roles in TeamCity:

• Administrators

• Users

• Guests

TeamCity Administrators can create the first administrative account on TeamCity, create users accounts, grant licenses and set up projects and build configurations.

Common users can access all features except those available only to Administrators.

Guest users do not need any licenses or registration to access TeamCity. The number of users logged in to TeamCity as guests is not limited. Guest users can access rather limited number of TeamCity's features. In particular, guests can view all projects and build configurations but cannot customize the view of the Projects page. Guest users cannot access the following features:

• starting new builds and stopping running builds,

• monitoring the status of code integration on My Changes page,

• configuring notificationRuleand receiving any notifications (both via IntelliJ IDEA plugin for TeamCity and Windows Tray Notifier).

See how to Enabling Guest Login.

Administrator

See account

Agent Requirement

Agent requirements are used in TeamCity to specify whether particular build configuration can be run on the particular build agent.

When a build agent registers on the TeamCity server, it provides information about its configuration, including values of environment variables and system properties. These parameters include settings specified in the buildAgent.properties file.

On the Agent Requirements, administrator can specify some requirements for the values of these parameters. For instance, if particular build configuration must run only on Windows build agents, administrator specifies this by adding a requirement that system property os.name on the build agent must contain Windows string.

If properties and environment variables on the build agent do not fulfill requirements specified for the build configuration, this build agent becomes incompatible with this build configuration (you can see this on the Agent Requirements for this build configuration or on the "Compatible agents" page). Name of the incompatible property is shown in the Web interface.

Sometimes build configuration may become incompatible with build agent if build runner for this configuration cannot be initialized on this build agent. For instance, .NET build runners do not initialize on UNIX systems.

There are also implicit requirements. For instance, if you define some build runner parameter as reference to another property, like %env.JDK_1_6%/lib/*.jar, this will implicitly add an agent requirement for existence of referenced property, i.e. env.JDK_1_6 should be defined. To define such property you may either specify it in the buildAgent.properties file, or set environment variable JDK_1_6 on the build agent, or specify value using Properties and environment variables screen (in the latter case, the same value of the property for all build agents will be used).

Agent Working Directory

Agent working directory - a directory of an agent where all projects are built. By default, this is agent installation folder/work directory.

To modify this path, navigate to buildAgent.properties file and edit the value of the workDir property (you do not need to restart agent after this).

Artifacts

Artifacts are files and folders produced by the build, uploaded to the server and available for download (installer, WAR file, log files, etc). Artifacts of the finished build stay on the server and are available for Downloading Artifacts until the build in Clean-Up-Policy. After finishing a build, TeamCity searches for the artifacts in the build working directory and uploads them to the server.

Artifacts of a build are specified on the build runner settings page in a text field in a special format:

file_name|directory_name|Ant-like wildcard [ => target_directory ] [, ...]

Whildcards are supported since TeamCity 2.1.

First, you specify either file name (to publish the file), or directory name (to publish all the files and subdirectories), or wildcard (to publish all matching files). The names are relative to the build working directory. This can optionally be followed by => symbols with the target directory name. The matching files will be published under the specified target directory. If target directory is omitted the files are published in the root of the build artifacts. Wildcard are Ant-like. When whildcard is used files are published preserving their directory structure. You can specify multiple sets delimiting them with commas.

Examples:

• install.zip - publish file named install.zip in the build artifacts

• dist - publish content of the directory "dist"

• target/*.jar - publish all jar files in the "target"

• target/**/*.txt => docs - publish all txt files found under "target" directory and its subdirectories. The files will be available in the build artifacts under the "docs" directory.

• reports => reports, distrib/idea*.zip - publish reports directory as "reports" and files matching "idea*.zip" from "distrib" directory into artifacts root.

Refer to the sections:

• Configuring Artifact Dependencies

• Artifacts Dependencies

Authentication  Schemes

TeamCity supports the following authentication schemes:

• Default Authentication (cross-platform): Users database is maintained by TeamCity. New users are added by TeamCity administrator (in administration area section) or user are self-registered if <free-registration allowed="true" /> tag is specified.

• NT Authentication (Windows platforms only): This scheme requires that TeamCity server is installed under Windows 2000, Windows XP or Windows Server 2003. All NT domain users that can log on to the machine running TeamCity server, can also login into TeamCity using the same credentials. i.e. to login to TeamCity users should provide user name in the form DOMAIN\username and their domain password.

• LDAP Authentication (cross-platform): Authentication is performed by direct login into LDAP with credentials entered into the login form.See Configuring Authentication Scheme procedural topic and Edit Server Configuration reference.

Refer to the sections:

• Configuring Authentication Scheme

• Authentication Settings

Build Agent

Build agent is a computer running a build. Each build agent possesses a number of predefined parameters that make it compatible for creating certain builds.

TeamCity has a system of leveraging the workload between several build agents which is called Build Grid.

In TeamCity build agents can be enabled / disabled and connected / disconnected. Agent is considered connected if it is registered on a server and responds to server commands, otherwise it is disconnected. Both connected and disconnected agents can be enabled or disabled. Builds are scheduled to enabled agents only. A new agent which is registered on the server for the first time will be disabled by default. TeamCity administrator can disable and enable agents from the web UI.

Build Configuration

Build Configuration describes a class of builds of particular type, or a procedure used to create builds. Examples of build configurations are integration builds, release builds, nightly builds, etc. Build configuration can be paused. In this case build triggers for this build configuration are disabled until the configuration is unpaused.

Refer to sections:

• Creating and Editing Build Configurations

• Create Edit Build Configuration

Build Grid

A mechanism used in TeamCity allowing to simultaneously create builds of multiple projects utilizing the pool of computers available at the software company.

Build States

A build passes through several states which can be easily identified in the user interface. The build state is updated automatically, so you never need to refresh the page to get the live state of the build.

The states of a personalBuilds are identified with similar icons (, etc. ).

Build Configuration States

In general, build configuration state reflects the state of its last finished build (except personal builds which do not affect build configuration state). Also, the build configuration state will change to" failure" when there's at least one running and failing build, even when the last finished build was successful.

Build Counter

The unit of increasing the buildNumber.

Build History

The record of past builds produced by TeamCity.

Build Log

A list of the events which took place when creating a build.

Build Numbering

Each build in TeamCity is assigned a build number. This number is shown in the UI and it can be referenced from various places. You can also get access to the build number in your build, using either build.number system property or BUILD_NUMBER environment variable. You can specify how build numbers are composed on the general Administration for each build configuration. The primary setting for this is "Build number format", an arbitrary string that can reference either build counter or VCS changeset number.

To reference build counter, use pattern {0} - this pattern will be replaced with increasing counter (which can be edited in "Build Counter" setting). To reference VCS changeset number, use pattern {build.vcs. number. 1} - this pattern will be replaced with actual changeset number from the VCS. As long as TeamCity supports several VCS for each project, there could be {build.vcs. number. 2} and more, depending on number of VCS used.

Build Trigger

Build trigger is an event that initiates new build. In TeamCity it can be:

• Appearance of changes in the version control system storing the source files for the particular build configuration

• Specified time

• Build completion

Build Runner 

Build runner is a mechanism that executes a build of a certain type.

Build Queue

A sequence of builds which TeamCity follows.

Build Working Directory

Build working directory is a directory where all project's sources reside and the process of creating builds starts. If the VCS checkout mode property of the build configuration is set to Automatically on server, the agent working directory/Server/project name directory is used as a build working directory. If the VCS checkout mode property is set to Automatically on agent, the agent working directory/Agent/project name directory is used as a build working directory.

If for some reasons this scenario does not match your requirements (for example, the process of creating builds depends on some particular directory), you may want to specify the build working directory via TeamCity's user interface on the Build Runners configuration page.

You may refer to the current value of build working directory via build.working.dir property provided by TeamCity.

Change

Any modification of the source code which you introduce. If a change has been committed to the version control system, but yet included in a build, it is considered pending for a certain build configuration.

Change States

Clean Sources

Cleaning sources means that the project sources are deleted from the build agent, when the next build of the selected build configuration is created on this agent. It is recommended to perform such action if some problems to the source code occurred (for example, the sources may have been broken).

You can also enable automatic cleaning the project sources before build starts, if you check the Clean all files before build option on the Create Edit Build Configuration page.

Clean-Up Policy

A policy that defines how to clean-up builds data (build log messages, changes, artifacts and so on). Clean-up policy contains a number of rules, which can be defined for a specific build configuration, for all configurations in a project or for all projects and build configurations. In each rule, the administrator can define a number of successful builds to preserve, and / or age of builds that should be kept in history (e.g. keep builds for 7 days). These rules do not work for pinned builds (see Pinned-Build).

Each rule has a priority. More specific rule has higher priority than less specific. For example, a rule for a build configuration will have higher priority than a rule for a project, where this build configuration belongs. If there is more than one rule that applies to the same build configuration, the rule with higher priority will be used.

See Build History Clean-Up Policy for more details about clean-up policies configuration.

Code Coverage

A number of metrics that measure how your code is covered by unit tests. In TeamCity the code coverage is available for Ant and Ipr build runners. The engine is based on the EMMA open-source toolkit.

Code Duplicates

The Duplicates build runner allows to catch similar code fragments and provides a comprehensive report on repetitive blocks of code discovered in your code base.

Code Inspection

Inspections build runner allows to verify and maintain the quality of your code by looking for common problems and antipatterns.

Continuous Integration

Continuous integration is a software engineering term describing a process that completely rebuilds and tests an application frequently. Generally it takes the form of a server process or daemon that

1. monitors a file system or version control system (e.g. CVS) for changes

2. runs the build process (e.g. a make script or Ant-style build script)

3. runs test scripts (e.g. JUnit or NUnit)

Continuous integration is also associated with Extreme programming and other agile software development practices.

Following the principles of Continuous Integration, TeamCity allows users to monitor the software development process of the company, while improving communication and facilitating the integration of changes without breaking the established practices.

Dependent Builds

In TeamCity one build configuration can depend on one or more configurations. Currently TeamCity supports two types of dependency:

• execution dependency - completion of a build of some configuration can trigger build of another build configuration

• artifacts dependency - artifacts of a build of some configuration can be made available for a build of another build configuration

Delayed Commit

An approach which allows to avoid the situation of getting the defective code into a build, so the process of the entire team is not affected in any way.

The submitted code changes first go through testing. If all tests succeed, TeamCity automatically submits the changes to version control. From there, they will automatically be integrated into the next TeamCity build. If any test fails, the code is not committed, and the submitting developer gets a notification by his/her preferred means.

Guest

See account

Licensing Policy

TeamCity is to be licensed per user account on the server. For details, please check the license agreement available at http://www.jetbrains.com/teamcity/buy/license.html.

Notifications

TeamCity provides flexible possibilities to inform the developers about the status of the project they are interested in. Notification involves sending messages to the users by means of the supported notifier, according to the defined notificationRule.

Notification Conditions

Notification conditions are the events you want to be notified about. The following events are supported:

• Build failed

• Notify on the first error

• Build started

• Build successful

• Responsibility changes

Refer to the description of the Notifier Settings.

Notification Rules

Notification rule is defined by a set of watched projects and events you want to be notified about. You can also be notified on events originating from the builds with your changes.

TeamCity comes with the default notification rule. It will send you an email notification if a build with your changes has failed. This rule starts working after setting up the email address to send notifications to.

When a build generates an event, notification rules are checked in top-down order and the first that matches a build is used to determine whether to send a notification or not.

Notifier

TeamCity supports the following notifiers:

Project

In TeamCity, a 'project' is an entity that can have several VCS roots and buildCongifuration. The project has a name (usually corresponds to the name of a real project) and can have some meaningful description.

Project VCS Roots

Directories containing the source files for your project builds. The VCS roots are used to monitor the changes that users upload to the version control system and to reflect these changes in TeamCity's user interface.

Personal Builds

Developers can run "personal" builds remotely on TeamCity's build grid just the same as a "regular" build. The difference is the changed code is never committed to version control. If a personal build fails, no "real" build is affected. The developer receives immediate notification of problems and can then work on a fix.

Pinned Build

A build can be pinned to preserve it from being removed when executing the clean-up procedure stipulated by the cleanUpPolicy. See Pinning and Unpinning Builds.

Responsibility

In TeamCity if a build fails, the developer can take responsibility for breaking the build. As soon as he or she does it, this fact becomes visible to all other team members. See Taking Responsibility for a Failed Build.

Roles

See account

Remote Run

See Personal-Builds.

TeamCity data directory

By default, TeamCity data directory, is $HOME/.BuildServer. Alternatively, you can define this directory in one of the following ways:

• as a Tomcat system property teamcity.data.path

• in the TEAMCITY_DATA_PATH environment variable

User

See account

Version Control System

A system for tracking the revisions of the project source files.

VCS Checkout Subdirectory

The VCS checkout subdirectory is a relative path of a particular VCS that defines a subdirectory relative to the buildWorkingDirectory. All source files from this particular VCS get into this subdirectory. For example, if a project has two VCS roots, namely, path1 and path2, the structure of the catalogues before the build start is:

build working directory/path1 build working directory/path2

By default, this path is not specified, and the source files from the particular VCS get directly into the buildWorkingDirectory.

You might want to specify VCS checkout subdirectory, if the project source files are obtained from several VCS roots. If your source files are obtained from a single VCS root, it is not necessary.