Space Details Key: TCD3 Name: Teamcity 3.X Documentation Description: This Is Jetbrains Teamcity 3.X Reference Documentation
Space Details Key: TCD3 Name: TeamCity 3.x Documentation Description: This is JetBrains TeamCity 3.x reference documentation. Creator (Creation Date): pk (Jan 23, 2007) Last Modifier (Mod. Date): yaegor (Apr 09, 2008) Available Pages • TeamCity Documentation • TeamCityReference • _What's New in TeamCity 3.0 • What's New in TeamCity 3.1 • Concepts • Agent Requirements • Agent Working Directory • Authentication Scheme • Build Agent • Build Artifact • Build Checkout Directory • Build Configuration • Build Configuration State • Build Grid • Build History • Build Log • Build Numbering • Build Queue_ • Build Runner • Build State • Build Tag • Build Trigger • Build Working Directory • Change • Change State • Clean Sources • Clean-Up Policy • Code Coverage • Code Duplicates • Code Inspection • Continuous Integration • Dependent Build • Editions • Licensing Policy
Document generated by Confluence on Jun 16, 2008 13:43 Page 1 • Notification • Notification Conditions • Notification Rules • Notifier • Permission • Personal Build • Pinned Build • Pre-Tested (Delayed) Commit • Project • Remote Run • Responsibility • Role • RSS Feed • Run Configuration Policy • Security • Supported Platforms and Environments • TeamCity Data Directory • Testing Frameworks • User Account • VCS Root • Version Control System • Developing TeamCity Plugins • Agent Side Extensions • Plugin API FAQ • Server Side Extensions • Statistics customization • Typical Plugins • Web UI Extensions • Installation and Upgrade • Installation • Installing Additional Plugins • Installing and Configuring the TeamCity Server • Setting up and Running Additional Build Agents • Migrating to an External Database • Setting up an External Database • TeamCity Data Backup • Upgrade • Upgrade Notes • Installing Tools • Eclipse Plugin • IntelliJ IDEA Plugin • Syndication Feed
Document generated by Confluence on Jun 16, 2008 13:43 Page 2 • Visual Studio Plugin • Windows Tray Notifier • System Administrator Reference • Configuring the Server • Accessing Server from Scripts • Authentication Settings • Build Script Interaction with TeamCity • Changing user password with default authentication scheme • Configuring Server URL • Configuring UTF8 Character Set for MySQL • Enabling Guest Login • Including Third-Party Reports in the Build Results • Mapping External Links in Comments • Using HTTPS to access TeamCity server • Enabling the Status Widget for Build Configurations • Enterprise License Expiration • Logs of Internal Events • Managing Projects • Assigning Build Configurations to Specific Build Agents • Configuring Artifact Dependencies • Configuring Build Runners • .NET Testing Frameworks Support • Additional Functionality in MSBuild Scripts • Ant_ • Maven2_ • NAnt_ • Sln2005_ • Sln2008_ • Configuring Build Triggers • Configuring VCS Settings • Creating and Editing Build Configurations • Notifier Templates Configuration • Patterns For Accessing Build Artifacts • System Properties for Running the Server • System Properties of a Build Configuration • Third-Party License Agreements • Troubleshooting • Known Issues • Reporting Issues • UI Reference • Administration • Build History Clean-Up Policy • Create Edit Build Configuration
Document generated by Confluence on Jun 16, 2008 13:43 Page 3 • 1.General Settings • 2.Version Control Settings • ClearCase • CVS • New Edit VCS Roots • Perforce • StarTeam • Subversion • Team Foundation Server • Visual Source Safe • 3.Build Runners • Ant • Duplicates Finder (.NET) • Duplicates Finder (Java) • Inspections • Ipr • Maven2 • MSBuild • NAnt • Simple Command Runner • sln2003 • sln2005 • sln2008 • 4.Build Triggering • Dependencies • Other Triggers • Schedule • Cron Expression Build Trigger • VCS Triggers • 5.Artifact Dependencies • 6.Properties and environment variables • 7.Agent Requirements • Create Edit Project • Licenses • Server Configuration • Email and Jabber Notifier Settings • User Accounts • Assign Roles • Edit General Settings of the User • VCS Roots • Agents • Agent Details • Build Configuration Home Page
Document generated by Confluence on Jun 16, 2008 13:43 Page 5 TeamCity Documentation
This page last changed on Feb 25, 2008 by yaegor. Welcome to TeamCity 3.x
TeamCity is a distributed build management and continuous integration system that allows your team to run and monitor your software building process while improving team communication, productivity and the integration of changes. With TeamCity:
• the process of integrating changes becomes a core part of your daily activities, • integration problems are discovered even before the build is complete, • you are notified only about the events you are interested in, • the process of creating builds is quick and transparent.
TeamCity's basic unit of work is a software build. To build your software using TeamCity, you need to have at least one "Build Agent" - a build computer with a set of predefined parameters (such as system and environment variables, JDK version, etc). The build agents are arranged into a build grid. Each software build, in turn, has its own configuration - a set of actions and parameters specified for it. These include the build runner, build schedule, etc. The build agent must meet the builds configuration's requirements: if there is a free build agent that meets the build configuration requirements, the build is started. Otherwise, the build is put into the queue and is processed when a compatible build agent becomes free.
Have a "10,000-foot look" at TeamCity, and the IDE's, frameworks, version control systems and means of monitoring it supports. Point to a component on the diagram below and jump to its description:
Document generated by Confluence on Jun 16, 2008 13:43 Page 6 See also:
TeamCity 2.x documentation
Document generated by Confluence on Jun 16, 2008 13:43 Page 7 TeamCityReference
This page last changed on Nov 22, 2007 by mio.
TeamCity Reference
Document generated by Confluence on Jun 16, 2008 13:43 Page 8 _What's New in TeamCity 3.0
This page last changed on Dec 18, 2007 by yaegor. What's New in TeamCity 3.0
Please review the Upgrade Notes. TeamCity Professional and Enterprise Editions
TeamCity now comes in Professional and Enterprise editions. Professional edition is free! and allows you to access all its features except some limitations while TeamCity Enterprise is more feature-rich with unlimited number of users and projects running at a time. Per-project roles and permissions
With the introduction of two TeamCity editions, different types of user roles and access rights are now available:
• TeamCity Professional has a fixed set of roles for all projects (guests, users, and system administrators). • The Enterprise edition enables you to assign one or several roles for users in the same project, and users will have different types of permissions. New Licensing Policy
You don't need any licenses to work with TeamCity Professional edition. The Enterprise edition provides more possibilities and requires commercial, EAP, evaluation or an open source license. Additional agents for each edition require per-agent licenses. Build Statistics Charts
Now TeamCity collects the info on the builds results over time and provides a set of visual reports, or build statistics charts, which allow to monitor your projects' health. The statistics display is customizable, and you can easily add your own graphs. Multiple Improvements Related to VCS Integration
• StarTeam support • VCS labels for the finished builds that have CVS, Subversion, Perforce, StarTeam, or ClearCase VCS roots • Sharing identical repository roots across different projects • User-based filters in VCS triggering • Per-Build Configuration VCS roots • Per-Build Configuration quiet period • Per-VCS root usernames • Per-VCS root modification check interval Improved Quality Maintenance
• .NET Duplicates finder enables you to catch similar code fragments of your C# and Visual Basic .NET code in Visual Studio 2003, 2005 and 2008 solutions. • Java Inspections and Duplicates for Maven2 projects • Pre-tested commit from Visual Studio for Subversion Miscellaneous
• Possibility to view thread dump of the Java and .Net build processes • Hanging builds are marked in the UI, in addition to the regular notification
Document generated by Confluence on Jun 16, 2008 13:43 Page 9 • Refined interface of the Build Queue tab, which now shows expected build start and finish time, the build agent where TeamCity plans to run a build, build triggering reason and time, and the list of build agents which can run the build.
• Build tags
• Search by the build number, build tag, project/configuration name
• RSS feeds: you can configure syndication feed for the projects and events you want to be notified about. • Ability to customize build status from the build script • Ability to download build log • Ability to assign agents to specific build configurations only
Document generated by Confluence on Jun 16, 2008 13:43 Page 10 What's New in TeamCity 3.1
This page last changed on Mar 06, 2008 by yaegor. What's New in TeamCity 3.1
Additional Support
• Support for NAnt 0.86 beta 1 • More flexible use of scripts using the Build Working Directory • Windows Authentication for Unix-like computers Agent Related Improvements
• Agent filter on build history • Quick search for build on specific agent • Agent statistics Notification Enhancements
• First failure after success/success after failure notifications • Ability to watch all projects • TLS support for e-mail sending Miscellaneous
• Build scheduling with CRON expressions • Time to fix tests statistics • Parallel tests running support • Syntax highlighting in duplicates viewer • Scope filter for the duplicates and inspections browsers • Publishing artifacts before the build is finished • Ability to report tests via standard output • Improved Clean-Up Policy - Select the data to clean: artifacts, history, statistics. • Migrating to external database • Filter by test name on Tests tab
Document generated by Confluence on Jun 16, 2008 13:43 Page 11 Concepts
This page last changed on Nov 22, 2007 by mio. Concepts
This part gives a list of basic terms and their definitions, that will help you successfully work with TeamCity.
• Agent Requirements • Agent Working Directory • Authentication Scheme • Build Agent • Build Artifact • Build Checkout Directory • Build Configuration • Build Configuration State • Build Grid • Build History • Build Log • Build Numbering • Build Queue_ • Build Runner • Build State • Build Tag • Build Trigger • Build Working Directory • Change • Change State • Clean Sources • Clean-Up Policy • Code Coverage • Code Duplicates • Code Inspection • Continuous Integration • Dependent Build • Editions • Licensing Policy • Notification • Notification Conditions • Notification Rules • Notifier • Permission • Personal Build • Pinned Build • Pre-Tested (Delayed) Commit • Project • Remote Run • Responsibility • Role • RSS Feed • Run Configuration Policy • Security • Supported Platforms and Environments • TeamCity Data Directory • Testing Frameworks • User Account • VCS Root • Version Control System
Document generated by Confluence on Jun 16, 2008 13:43 Page 12 Agent Requirements
This page last changed on Apr 21, 2008 by ivrina. Agent Requirements
Agent requirements are used in TeamCity to specify whether a build configuration can run on a particular build agent.
When a build agent registers on the TeamCity server, it provides information about its configuration, including its environment variables, system properties and additional settings specified in the buildAgent.properties file.
The administrator can specify required environment variables and system properties for a build configuration on the build configuration's Agent Requirements page. For instance, if a particular build configuration must run on a build agent running Windows, the administrator specifies this by adding a requirement that the os.name system property on the build agent must contain the Windows string.
If the properties and environment variables on the build agent do not fulfill the requirements specified by the build configuration, then the build agent is incompatible with this build configuration. The Agent Requirements page lists both compatible and incompatible agents.
Sometimes the build configuration may become incompatible with a build agent if the build runner for this configuration cannot be initialized on the build agent. For instance, .NET build runners do not initialize on UNIX systems.
There are also implicit requirements. For instance, if you define a build runner parameter as a reference to another property, like %env.JDK_1_6%/lib/*.jar, this will implicitly add an agent requirement for the referenced property, i.e. env.JDK_1_6 should be defined. To define such properties you may either specify them in the buildAgent.properties file, or set the environment variable JDK_1_6 on the build agent, or specify the value on the Properties and environment variables page (in the latter case, the same value of the property for all build agents will be used).
See also:
• Concepts: Build Agent, Build Configuration • UI Reference: Agent Requirements • System Administrator Reference: Assigning Build Configurations to Specific Build Agents
Document generated by Confluence on Jun 16, 2008 13:43 Page 13 Agent Working Directory
This page last changed on Apr 21, 2008 by ivrina. Agent Working Directory
Agent working directory is the directory on an agent where all projects are built. By default, this is the /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).
See also:
• Concepts: Build Agent • UI Reference: Agents
Document generated by Confluence on Jun 16, 2008 13:43 Page 14 Authentication Scheme
This page last changed on Feb 06, 2008 by chamilton. Authentication Scheme
TeamCity supports the following authentication schemes:
• Default Authentication (cross-platform): A database of users is maintained by TeamCity. New users are added by the TeamCity administrator (in the administration area section) or they can register themselves if the tag is specified. • NT Authentication (Windows platforms only): This scheme requires that the TeamCity server is installed on Windows 2000, Windows XP or Windows Server 2003, however support for Unix-like computers was introduced in TeamCity 3.1. All NT domain users that can log on to the machine running the TeamCity server, can also log in to TeamCity using the same credentials. i.e. to log in to TeamCity users should provide domain and user name (DOMAIN\username) and their domain password. • LDAP Authentication (cross-platform): Authentication is performed by directly logging into LDAP with credentials entered into the login form. NT and LDAP authentication are only available in TeamCity Enterprise Edition. If the Professional Edition is configured to use NT or LDAP authentication builds will not run.
See also:
• Concepts: Authentication Settings • UI Reference: Server Configuration
Document generated by Confluence on Jun 16, 2008 13:43 Page 15 Build Agent
This page last changed on May 20, 2008 by ivrina. Build Agent
A build agent is a computer capable of running a build. Each build agent possesses a number of predefined parameters that make it compatible for creating certain builds. Build agents are joined into a build grid.
In TeamCity build agents can be authorized/unauthorized, enabled/disabled, and connected/disconnected.
Status Description Connected An agent is connected if it is registered on the TeamCity server and responds to server commands, otherwise it is disconnected. This status is determined automatically. Authorized Agents are manually authorized via the web UI. Only authorized build agents can run builds. The number of simultaneously authorized agents cannot exceed the number of agent licenses in your license pool. When an agent is unauthorized, a license is freed and a different build agent can be authorized. Purchase additional licenses to expand the number of agents that can concurrently run builds. When an agent is connected to the server for the first time is unauthorized and requires manual authorization to run the builds. If a build agent is installed and running on the same computer as TeamCity build server, it is authorized automatically. Enabled Agents are manually enabled/disabled via the web UI. The TeamCity server only distributes builds to agents that are enabled. Disabled agents can still run builds, however they must be assigned to them manually. This feature is generally used to temporarily remove agents from the build grid when they consistently have problems during the build process.
When a new agent is registered on the server for the first time, it will be unauthorized by default.
All agents connected to the server must have unique agent name.
Only users with certain roles can manage agents. See Permission for more information.
See also:
• Installation and Upgrade: Installing and Running Build Agents • Concepts: Agent Working Directory | Build Grid | Editions | Permission • Administrator reference: Assigning Build Configurations to Specific Build Agents • UI Reference: Agents
Document generated by Confluence on Jun 16, 2008 13:43 Page 16 Build Artifact
This page last changed on Jun 03, 2008 by yaegor. Build Artifact
Artifacts are files produced by a build. After finishing a build, TeamCity searches for artifacts in the build's checkout directory according to the specified artifact patters. Matching files are then uploaded to the server, where they become available for download. Artifacts stay on the server and are available for download until the artifacts for the build are cleaned up. Examples of artifacts are installers, WAR files, reports, log files, etc.
Artifacts of a build are specified on the general settings page using comma-, or newline- separated values of the format: file_name|directory_name|Ant-like wildcard [ => target_directory ]
The format contains:
• file_name — to publish the file. The file will be published by its name. • directory_name — to publish all the files and subdirectories within the directory specified. The files will be published preserving the directories structure under the directory specified (the directory itself will not be included). • wildcard — to publish files matching Ant-like pattern ("*" and "**" wildcards are only supported). The files will be published preserving the structure of the directories matched by the wildcards (directories matched by "static" text will not be created). That is, TeamCity will create directories starting from the first occurrence of the wildcard in the pattern. • target_directory — the directory in the resulting build's artifacts that will contain the files determined by the left part of the pattern.
The names are relative to the build checkout directory.
An optional part starting with => symbols and followed by the target directory name can be used to publish the files into the specified target directory. If target directory is omitted the files are published in the root of the build artifacts. You can use "." (dot) as reference to the build checkout directory.
Examples:
• install.zip — publish file named install.zip in the build artifacts • dist — publish the content of the dist directory • target/*.jar — publish all jar files in the target directory • target/**/*.txt => docs — publish all the txt files found in the 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 the distrib directory into the artifacts root. TeamCity stores artifacts on disk in a directory structure that can be accessed directly (e.g. by configuring the Operating System to share the directory over the network). The artifacts are stored under /system/artifacts folder. Storage format is described in the TeamCity Data Directory section. Build artifacts are not archived in TeamCity and stay as they are (uncompressed).
You can download artifacts of a build via the web UI from the Artifacts column of the Projects page, from the Overview tab of the Build Configuration Home Page or from the Artifacts tab of the Build Results page. Artifacts downloading can be automated as described in the section Patterns For Accessing Build Artifacts.
Build artifacts can also be uploaded to the server while the build is still running. To instruct TeamCity to upload the artifacts, build script should be modified to send service messages
Artifacts are stored on the disk on the server, under TeamCity Data Directory/artifacts/// directory. The artifacts can be copied
Document generated by Confluence on Jun 16, 2008 13:43 Page 17 directly form the directory on the server (if OS is configured to provide access for it). TeamCity computer's administrator can delete artifacts directly form the disk. In this case, build's artifacts will no longer be available.
Document generated by Confluence on Jun 16, 2008 13:43 Page 18 Build Checkout Directory
This page last changed on Apr 28, 2008 by ivrina. Build Checkout Directory
The build checkout directory is the directory where all of the project's sources reside. If the VCS checkout mode property of the build configuration is set to Automatically on server or Automatically on agent, TeamCity places the sources directly into the checkout directory.
If not specified, the following directory is used: /. The VCS settings hash code is calculated based on VCS roots and VCS settings used by the build configuration. Effectively, this means that the directory is shared between all the build configurations with the same VCS settings.
If you need to know the directory used by a build configuration, you can refer to /directory.map generated file which lists build configurations with the directory used by them.
If for some reason default directory does not match your requirements (for example, the process of creating builds depends on some particular directory), you may want to specify your own build checkout directory.
In the build script you may refer to the effective value of build checkout directory via the teamcity.build.checkoutDir property provided by TeamCity.
The checkout directory is automatically cleaned up if not used (no builds use it as checkout directory) for a specified period of time (by default it is two weeks). The time frame can be changed by specifying teamcity.agent.build.checkoutDir.expireHours agent property.
If you upgrade to TeamCity 3.x from previous versions, please refer to Upgrade Notes describing several checkout directory-related issues.
Document generated by Confluence on Jun 16, 2008 13:43 Page 19 Build Configuration
This page last changed on Apr 11, 2008 by ivrina. 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. A build configuration is characterized with its state. In particular, it can be paused or active. If a build configuration is paused, its build triggers are disabled until the configuration is activated.
You can explore details of a build configuration in its home page, and change its settings in the editing page.
A build configuration can be paused or activated in several places of the TeamCity UI:
• The Build Triggering section of the Administration page.
• The Actions link on the Build Configuration Home Page toolbar
• The Current status field of the Overview tab of the Build Configuration Home Page
Document generated by Confluence on Jun 16, 2008 13:43 Page 20 Build Configuration State
This page last changed on Apr 22, 2008 by ivrina. Build Configuration State
In general, build configuration state reflects the state of its last finished build (except personal builds which do not affect the build configuration state). Also, the build configuration state will change to "failed" when there's at least one currently running and failing build, even if the last finished build was successful. You can view the build configuration status in the Projects tab.
Icon Build configuration state Description paused Build configuration was paused, so that no builds are triggered automatically. unknown There were no finished builds in this configuration. successful The last build executed successfully. failed The last build with this build configuration executed with errors or one of the currently running builds is failing. responsibility taken Some developer is trying to fix the problems with the failed builds (see Responsibility). probably fixed The developer who took responsibility for the failed builds has submitted a fix; in this case the status will not change to successful until the build with the fix has executed successfully.
See also:
• Concepts: Build Configuration | Build State | Change State • UI Reference: Projects | Create/Edit Build Configuration | Build Configuration Home Page | Build Triggering
Document generated by Confluence on Jun 16, 2008 13:43 Page 21 Build Grid
This page last changed on Apr 15, 2008 by ivrina. Build Grid
A build grid is a pool of computers (Build Agents) used by TeamCity to simultaneously create builds of multiple projects. The build grid employs currently-unused resources from multiple computers, any of which can run multiple builds and/or tests at a time, for single or multiple projects across your company.
Document generated by Confluence on Jun 16, 2008 13:43 Page 22 Build History
This page last changed on Nov 30, 2007 by chamilton. Build History
The build history is the record of past builds produced by TeamCity.
To view the build history, click the Projects tab, expand the desired project and build configuration, and click a build result link. In the Build history section of the Build Results page, click previous and next links to browse through, or click All history link to open the history page.
See also:
• UI Reference: Build Results
Document generated by Confluence on Jun 16, 2008 13:43 Page 23 Build Log
This page last changed on Nov 26, 2007 by mio. Build Log
Build Log is a list of the events which took place when creating a build. Build log is available in the Build Results page, and enables viewing a complete log, or important messages only.
You can download a full build log from the Build Results page using the link
Document generated by Confluence on Jun 16, 2008 13:43 Page 24 Build Numbering
This page last changed on Dec 05, 2007 by mio. 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 the build.number system property or the BUILD_NUMBER environment variable. You can specify how build numbers are composed on the General Settings page for each build configuration. The primary setting for this is the "Build number format", an arbitrary string that can reference either the build counter or the VCS changeset number.
To reference the build counter, enter {0} - the build counter will increase the number with each build (this can be edited in "Build Counter" setting). To reference the VCS changeset number, enter {build.vcs.number.1} - this will be replaced with the 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 VCSs used.
A build number format example:
1.0.{0}.{build.vcs.number.1}
See also:
• UI Reference: Create/Edit Build Configuration • Administrator's Reference: System Properties of a Build Configuration
Document generated by Confluence on Jun 16, 2008 13:43 Page 25 Build Queue_
This page last changed on Dec 03, 2007 by mio. Build Queue
The build queue is a list of build configurations that TeamCity will distribute to compatible build agents as they become available. You can move build configurations up or down in the queue on the Build Queue page.
See also:
• UI Reference: Build Queue
Document generated by Confluence on Jun 16, 2008 13:43 Page 26 Build Runner
This page last changed on Nov 23, 2007 by chamilton. Build Runner
Build runner is a mechanism that executes a build of a certain type. Build runners are configurable in the Build Runners section of the Create/Edit Build Configuration page.
See also:
• UI Reference: Build Runners
Document generated by Confluence on Jun 16, 2008 13:43 Page 27 Build State
This page last changed on Feb 18, 2008 by chamilton. Build State
The build state appears next to each build under the expanded view of the build configuration on the projects tab.
Build States
Icon State Description running successfully A build is running successfully. successful A build finished successfully in all specified build configurations. running and failing A build is failing. failed A build failed at least in one specified build configuration.
Personal Build States
Icon State Description running successfully A personal build is running successfully. successful A personal build has completed successfully for all specified build configurations. running and failing A personal build is running with errors. failed A personal build failed at least in one specified build configuration.
A build can also appear with the icon:
hanging or outdated The tooltip will display additional information about the warning.
See also:
• Concepts: Build Configuration State | Change | Change State • UI Reference: My Changes | Projects | Build Results
Document generated by Confluence on Jun 16, 2008 13:43 Page 28 Build Tag
This page last changed on Mar 12, 2008 by ivrina. Build Tag
Build tags are labels that can help you to:
• organize history of your builds • quickly navigate to the builds marked with the specific tag • search for a build with a particular tag
You can assign any number of tags for a single build, for example, EAP or release.
Tag a particular build on the Overview tab of the Build Results page, or in the Overview tab of the Build Configuration Home Page. To do that, click the down-arrow button in the Tags column of the desired build number and type the desired tag name in the Edit tags dialog. The build tag appears in the Recent history of builds on this page. Clicking the tag you filter out all of the builds in the history and show only builds marked with the tag.
Additionally you can search for builds with particular tags using the search field on the Projects page.
See also:
• UI Reference: Build Configuration Home Page| Build Results
Document generated by Confluence on Jun 16, 2008 13:43 Page 29 Build Trigger
This page last changed on Apr 22, 2008 by ivrina. Build Trigger
Build trigger is an event that initiates a new build. The build is put into the build queue and is run when there are idle agents that can run it.
In TeamCity, build can be triggered by:
• VCS trigger — the build is triggered when changes are detected in the version control system roots attached to the build configuration • Schedule trigger — the build is triggered at a specified time • Dependency trigger — after a build of another build configuration completes successfully • Manually — a user clicked Run button for a build configuration
A build can also be triggered by an HTTP GET request.
Document generated by Confluence on Jun 16, 2008 13:43 Page 30 Build Working Directory
This page last changed on May 07, 2008 by yaegor. Build Working Directory
The build working directory is the directory set as current for the build process. By default, this is the same directory as the Build Checkout Directory. If the build script needs to run from a location other than the checkout directory, then you can specify it explicitly using the Working Directory field on the settings page of the build runner.
Not all of the runners provide the working directory setting.
The path entered in the Working Directory field can be either absolute or relative to the build checkout directory. When using this option, all of the other paths should still be entered relative to the checkout directory.
Document generated by Confluence on Jun 16, 2008 13:43 Page 31 Change
This page last changed on Apr 24, 2008 by ivrina. Change
Any modification of the source code which you introduce. If a change has been committed to the version control system, but not yet included in a build, it is considered pending for a certain build configuration.
TeamCity suggests several ways to view changes:
• My Changes page shows the list of builds that contain changes, committed by the current user and already included in builds. • Pending changes are accessible from the Project page, build configuration page, or build results page.
Viewing and analyzing changes involves the following possibilities:
• Observing actual changes that are already included in the build, in the Changes link of the Projects page. • Observing pending changes in the Pending Changes tab of the the Build Configuration Home Page. • Navigating to the related issues in a bug tracking system • Navigating to the source code and viewing differences • Taking responsibility for a failed build, if your changes have caused a build failure.
See also:
• Concepts: Version Control System | Build Configuration| Responsibility • UI Reference: Version Control Settings | Pending Changes | Build Results
Document generated by Confluence on Jun 16, 2008 13:43 Page 32 Change State
This page last changed on Mar 12, 2008 by ivrina. Change State
Change States
Icon State Description pending The change is scheduled to be integrated into a build that is currently in the build queue. Even if a change has been successfully integrated into a build, the change will appear as pending when it is scheduled to be added to a different build. running successfully The change is being integrated into a build that is running successfully. successful The change was integrated into build that finished successfully. running and failing The change is being integrated into a build that is failing. failed The change was integrated into a build that failed.
Personal Change States
Icon State Description pending The change is scheduled to be integrated into a personal build that is currently in the build queue. running successfully The change is being integrated into a personal build that is running successfully. successful The change was integrated into a personal build that finished successfully. running and failing The change is being integrated into a personal build that is failing. failed The change was integrated into a personal build that failed.
See also:
• Concepts: Build Configuration State | Build State | Change • UI Reference: My Changes
Document generated by Confluence on Jun 16, 2008 13:43 Page 33 Clean Sources
This page last changed on Apr 24, 2008 by yaegor. Clean Sources
Cleaning sources means that the previous project sources are deleted from the build agent and new project sources are checked out, when the next build of the selected build configuration is created on the agent. Cleaning sources is recommended if problems occurred with the source code (for example, the sources may have been broken).
You can also enable automatic cleaning the project sources before a build starts, if you check the option Clean all files before build on the Create/Edit Build Configuration> General Settings page.
You can invoke clean sources action for a build configuration (the checkout directory corresponding to the build configuration will be cleaned on all the agents) from the Build Configuration page (see "Actions" drop-down in the top right corner), or for an agent (all checkout directories on the agent will be cleaned before the next build in the corresponding directory) from the Agent Details page.
Document generated by Confluence on Jun 16, 2008 13:43 Page 34 Clean-Up Policy
This page last changed on Apr 04, 2008 by yaegor. Clean-Up Policy
A policy that defines how to clean up build data (build log messages, changes, artifacts and so on). The 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 of the projects. In each rule, the administrator can define a number of successful builds to preserve, and/or a length of time that builds should be kept in history (e.g. keep builds for 7 days). These rules do not apply to pinned builds (see Pinned Build).
Also preserved with no respect to clean-up policy are the builds that are used as source for artifact dependency in other builds.
Each rule has a priority. More specific rules have a higher priority than less specific rules. For example, a rule for a build configuration will have a higher priority than a rule for a project, which is part of the build configuration. If there is more than one rule that applies to the same build configuration, the rule with higher priority will be used.
Each clean-up rule defined what data to cleanup. In TeamCity 3.1 the options are: remove only the build artifacts, remove both artifacts and the build history entry (the build will be preserved only in the statistics charts), and remove everything.
See Build History Clean-Up Policy for more details about clean-up policies configuration.
Document generated by Confluence on Jun 16, 2008 13:43 Page 35 Code Coverage
This page last changed on Apr 17, 2008 by yaegor. Code Coverage
Code coverage is a number of metrics that measure how your code is covered by unit tests. Code coverage information displays for those build configurations, where this metric is configured in the Code Coverage section of a build runner (Build Configuration Home Page | Edit Build Configuration Settings | 3.Runners). In TeamCity the code coverage is available for Ant and Ipr build runners. The engine is based on the EMMA open-source toolkit.
View the code coverage summary in the Overview tab of the Build Results page; detailed report displays in the Code Coverage tab. Chart for code coverage is also available in the Statistics tab of the build configuration.
Document generated by Confluence on Jun 16, 2008 13:43 Page 36 Code Duplicates
This page last changed on Nov 29, 2007 by chamilton. Code Duplicates
Code Duplicates are repetitive blocks of code. The Duplicates Finder build runners search for similar code fragments and provide a comprehensive report on repetitive blocks of code discovered in your code base.
See also:
• UI Reference: Java Duplicates Finder | .NET Duplicates Finder | Build Results
Document generated by Confluence on Jun 16, 2008 13:43 Page 37 Code Inspection
This page last changed on Dec 05, 2007 by mio. Code Inspection
A code inspection is an automated code review that verifies and reports the quality of your code by looking for common problems and anti-patterns. More than 600 Java (as well as HTML, CSS, JavaScript) inspections are preformed by the Inspection Build Runner.
Inspection results are reported in the Code Inspection tab of the Build results page.
Document generated by Confluence on Jun 16, 2008 13:43 Page 38 Continuous Integration
This page last changed on Dec 03, 2007 by mio. 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:
• Monitors a file system or version control system (e.g. CVS) for changes. • Runs the build process (e.g. a make script or Ant-style build script). • 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 any established practices.
Document generated by Confluence on Jun 16, 2008 13:43 Page 39 Dependent Build
This page last changed on May 04, 2008 by ivrina. Dependent Build
In TeamCity one build configuration can depend on one or more configurations. Currently TeamCity supports two types of dependencies:
• 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
Document generated by Confluence on Jun 16, 2008 13:43 Page 40 Editions
This page last changed on Dec 01, 2007 by chamilton. Editions
TeamCity comes in two editions, that differ in functionality and cost.
• Professional edition: the basic edition that does not require any server license key and has limitations as described in the table below. • Enterprise edition: the fully-functional edition.
The differences between editions are the following:
Professional Enterprise User limit 20 unlimited Build configuration limit 20 unlimited Bundled Build Agents 3 3 Per-project roles support Support for authentication schemes other then default
More Build Agents can be added separately. The agent licenses can be used with either TeamCity edition. For more information about purchasing agent licenses, refer to the product page. The same TeamCity distribution is used for both editions. You can switch to Enterprise edition by entering a license key on the Licenses page in the Administration area.
Document generated by Confluence on Jun 16, 2008 13:43 Page 41 Licensing Policy
This page last changed on May 04, 2008 by ivrina. Licensing Policy
Each edition of TeamCity has its own licensing policy. TeamCity Professional does not require any license keys when using the predefined number of free agents. The Enterprise edition requires one of the following types of licenses:
• Commercial — no expiration date • Evaluation — has an expiration date and provides an unlimited amount of agents; the evaluation license can be obtained only once, a second evaluation key is not accepted after the previous one expires. • Open Source — this is a special type of license granted for open source projects, it is time-based, and provides an unlimited amount of agents.
If you need additional agents for either edition, you can purchase an additional agent license, which defines a number of additional agents you can use with TeamCity. The agent license does not expire.
Managing licenses is only available to users with the System or Project Administrator permissions: Administration > Licenses page
The TeamCity Licensing Policy does not impose any limitations on the number of instances for any of the IDE plugins or the Windows Tray Notifier. Upgrade
All TeamCity 1.x/2.x customers qualify for a free upgrade to TeamCity 3.x Enterprise edition. Please contact our sales department to receive your TeamCity Enterprise license key (make sure to provide your customer ID or any of your existing license keys).
In addition to the Enterprise edition, all TeamCity 1.x/2.x customers can enter their existing license keys in TeamCity 3.x to get a number of agents equal to the number of TeamCity 1.x/2.x user licenses. Accepted License Keys
The following license key types are accepted by TeamCity 3.x as agent keys:
• IDEA 6.0 key generated before Jan 15, 2007 — grants one agent license • TeamCity 1.x/2.x key — grants a number of agent licenses equal to the number of users licensed to use TeamCity 1.x/2.x • TeamCity 3.x enterprise key — grants enterprise version access • TeamCity 3.x agent key — grants one agent license • TeamCity 3.x evaluation key — grants temporary enterprise version access with unlimited agents; only one evaluation is allowed • TeamCity 3.x Open-Source key — grants time limited enterprise version access with unlimited agents
See also:
• Concepts: Edition | Build Agent
• Licensing: Licensing & Upgrade
Document generated by Confluence on Jun 16, 2008 13:43 Page 42 Notification
This page last changed on May 04, 2008 by ivrina. Notification
TeamCity provides wide range of notification possibilities to keep developers informed about the status of their projects. Notifications can be sent by e-mail, Jabber/XMPP instant messages and Atom/RSS feeds or can be displayed in the IDE and the Windows system tray. Notifications will be sent according to a set of defined notification rules.
Document generated by Confluence on Jun 16, 2008 13:43 Page 43 Notification Conditions
This page last changed on May 23, 2008 by ivrina. Notification Conditions
Notification conditions are events you want to be notified about. The following events are supported:
Event Description The build fails A build fails. Ignore failures not caused by my changes Notification is sent only if a build failure was caused by your changes. This option is available only if the Watch builds with my changes option was selected. The first failed build after a successful build This option is supported in TeamCity 3.1 The first build's failure occurs after a successful build. Notifications about subsequent failed builds will not be sent. This option is NOT available if the Watch builds with my changes option was selected. The build is successful A build is successful. The first successful build after a failed build This option is supported in TeamCity 3.1 The build is successful after a failed build. Notifications about subsequent successful builds will not be sent. This option is NOT available if the Watch builds with my changes option was selected. The first error occurs The very first error occurs in a build. Notification is sent immediately, even before the build is finished. The build starts A build starts. The build is probably hanging TeamCity detects that a build is probably hanging. The hanging build detection heuristics includes exceeded build estimate and no build messages received for a certain amount of time. Responsibility changes Any activity of a person that is responsible for a build's failure (e.g. this person takes responsibility for the failed build, or reports that problem is fixed, etc.) Notification about the first successful build after the fixes will also be sent.
Document generated by Confluence on Jun 16, 2008 13:43 Page 44 Notification Rules
This page last changed on Dec 03, 2007 by mio. Notification Rules
A notification rule is defined by selecting the projects and events that happen to those projects that you want to be notified about. You can also be notified about events originating from the builds with your changes.
TeamCity comes with a default notification rule. It will send you an email notification if a build with your changes has failed. This rule starts working after you enter the email address you want your notifications sent 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.
You can define notification rules for the different notifiers in the My Settings and Tools page. See Notifier Settings for details.
See also:
• Concepts: Notifiers • UI Reference: My Settings and Tools
Document generated by Confluence on Jun 16, 2008 13:43 Page 45 Notifier
This page last changed on Dec 01, 2007 by chamilton. Notifier
TeamCity supports the following notifiers:
Notifier Description Email Notifier Notifications regarding specified events are sent via email. IDE Notifier Displays the status of the build configurations you want to watch and/or the status of your changes. Jabber Notifier Notifications regarding specified events are sent via Jabber. System Tray Notifier Displays the status of the build configurations you want to watch in the Windows system tray, and displays pop-up notifications on the specified events. Atom/RSS Feed Notifier Notifications regarding specified events are sent via an Atom/RSS feed.
You can configure the notifier settings, create, change and delete notification rules in the Watched Builds and Notifications section of the My Settings and Tools page.
Document generated by Confluence on Jun 16, 2008 13:43 Page 46 Permission
This page last changed on May 04, 2008 by ivrina. Permission
A permission is an authorization granted to TeamCity users to perform particular operations. In TeamCity the administrator assigns roles to users. Each role has a set of permissions. A user can have different roles in different projects, and hence, the permissions are project-based.
Permissions in TeamCity Enterprise
In TeamCity Enterprise offers flexible uses of roles, which can be assigned users on a per-project basis.
Permissions can manually be added or removed from roles listed below by editing the roles- config.xml file in the config directory of the . When assigning roles, the view role permissions link in the Web UI will accurately display a list permissions for each role in accordance to how they have been manually re-configured. Enterprise Roles Permissions Project Viewer View project Project Developer Run/stop build, remove build from the queue, pin/unpin build, tag build, pause/activate build configuration, clean build configuration sources, take responsibility, view project, view build configuration settings, view VCS file content, manually label build, and reorder builds in the queue Agent Manager Change agent run configuration policy, and enable/ disable agent Project Administrator All of the project developer and agent manager permissions and edit project, change clean up rules, change user roles in a project, stop any personal build and remove it from the queue System Administrator All of the project administrator permissions and create/copy project, change shared VCS root, create/delete user account, modify user profile and roles, manage server licenses, change server settings, clean sources on an agent, authorize agent, configure server data cleanup, change own profile
Permissions in TeamCity Professional
In TeamCity Professional roles are fixed across all of the projects and permissions cannot be added or removed from a role. Professional Roles Permissions Guest View projects User Run/stop build and remove build from the queue, pin/unpin build, tag build, pause/activate build configuration, clean build configuration sources, take responsibility, view project, view build configuration settings, view VCS file content, manually label build, reorder builds in the queue Administrator All of the user permissions and change agent run configuration policy, enable/disable agent, edit project, change clean up rules, change user roles in a project, stop any personal build and remove it from the queue, create/copy project, change shared VCS root, create/delete user account, modify user profile and roles, manage server licenses, change server settings, clean sources on an agent, authorize
Document generated by Confluence on Jun 16, 2008 13:43 Page 47 agent, configure server data cleanup, change own profile
See also:
• Concepts: Role | User Account • UI Reference: My Settings And Tools
Document generated by Confluence on Jun 16, 2008 13:43 Page 48 Personal Build
This page last changed on May 04, 2008 by ivrina. Personal Build
A personal build is a build initiated as Remote Run or Pre-Tested Commit. Only users with "Project Developer" role can initiate a personal build.
The build uses the current VCS repository sources plus the changed files identified during pre-tested commit or remote run initiation. The results of the Personal Build can be seen in the "My Changes" view of the corresponding IDE plugin and on the My Changes page of the TeamCity web UI. Finished personal builds are listed in the builds history, but only for the users who initiated them.
The personal build feature requires tight integration with the version control system. The following combinations are currently supported:
• IntelliJ IDEA Plugin — Subversion, Perforce, CVS, Visual SourceSafe, ClearCase, StarTeam • Eclipse Plugin — Subversion • Visual Studio Plugin — Subversion, Team Foundation Server The same info is featured as a table on Remote Run page In order for Personal Build functionality to work properly using CVS, VSS and TFS version control systems, the VCS should be configured in exactly the same way on the TeamCity server and on the client computer (running the IDE). This means that the same VCS server names (disk name in the case of VSS) should be used.
See also:
• Concepts: Pre-tested Commit| Remote Run • Working with Tools: IntelliJ IDEA Plugin | Eclipse Plugin | Visual Studio Plugin
Document generated by Confluence on Jun 16, 2008 13:43 Page 49 Pinned Build
This page last changed on Dec 03, 2007 by mio. Pinned Build
A build can be "pinned" to prevent it from being removed when a clean-up procedure is executed, as stipulated by the clean-up policy.
You can pin or unpin a build in the Overview tab of the Build Configuration Home Page, or in the Overview tab of the Build Results page.
Document generated by Confluence on Jun 16, 2008 13:43 Page 50 Pre-Tested (Delayed) Commit
This page last changed on Feb 15, 2008 by chamilton. Pre-Tested (Delayed) Commit
An approach which prevents committing defective code into a build, so the entire team's process is not affected.
Submitted code changes first go through testing. If it passes all of the tests, TeamCity can automatically submit the changes to version control. From there, it will automatically be integrated into the next build. If any test fails, the code is not committed, and the submitting developer is notified.
The TeamCity plugins for IntelliJ IDEA, Microsoft Visual Studio 2005/2008 and Eclipse extend the respective IDE with the remote run and pre-tested commit features. Developers test their changes by performing a Remote Run. A pre-tested commit is enabled when commit changes if successful is selected.
For a list of Version Control Systems supported by each IDE please see supported platforms and environments.
See also:
• Concepts: Remote Run • Working with Tools: IntelliJ IDEA Plugin | Eclipse Plugin | Visual Studio Plugin
Document generated by Confluence on Jun 16, 2008 13:43 Page 51 Project
This page last changed on May 04, 2008 by ivrina. Project
Project is a simple grouping of the build configurations. The project has a name (usually corresponds to the name of a real project) and can have some meaningful description.
TeamCity uses project level for managing security. In TeamCity Enterprise Edition is it is possible to assign per-project roles to users. This makes it possible to assign users different permissions for each project. TeamCity Professional Edition lacks this feature and users are assigned permissions for all of the projects.
You can create and change projects in the Administration page. Use the Projects page to configure the visible projects that display in the overview.
See also:
• Concepts: Build Configuration • UI Reference: Administration | Projects | My Settings And Tools
Document generated by Confluence on Jun 16, 2008 13:43 Page 52 Remote Run
This page last changed on May 04, 2008 by ivrina. Remote Run
A remote run is a Personal Build initiated by a developer from one of the supported IDE plugins to test how the changes will integrate into the project's code base. Unlike Pre-tested Commit, no code is checked into the VCS regardless of the state of the personal build initiated via Remote Run.
For a list of Version Control Systems supported by each IDE please see supported platforms and environments.
See also:
• Concepts: Pre-tested Commit | Personal Build • Working with Tools: IntelliJ IDEA Plugin | Eclipse Plugin | Visual Studio Plugin
Document generated by Confluence on Jun 16, 2008 13:43 Page 53 Responsibility
This page last changed on Dec 04, 2007 by mio. 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.
Take responsibility for a failed build in:
• Overview tab of the Build Configuration Home Page • Overview tab of the Build Results page
See also:
• Concepts: Build Configuration State • UI Reference: Build Configuration Home Page | Build Results
Document generated by Confluence on Jun 16, 2008 13:43 Page 54 Role
This page last changed on May 04, 2008 by ivrina. Role
Role is a set of permissions granted to a particular user. Roles are assigned per-project. A user can have a role in a specific project or in all available projects, or no role at all. Depending on your TeamCity edition, different roles are available. You can associate a user with a set of roles, using the Assign roles dialog. This section describes:
• TeamCity Enterprise User Roles • TeamCity Professional User Roles
TeamCity Enterprise User Roles
The roles and permissions are described and can be modified in the roles-config.xml file stored in /config. Role Description System Administrator TeamCity System Administrators have no restrictions in their permissions. They can create and manage users accounts, authorize build agents and set up projects and build configurations, edit the TeamCity server settings, manage TeamCity licenses, etc. Project Administrator Project Administrator is a person who can customize the general settings of a project, build configuration settings and assign roles to the project users. Project Developer Project Developer is a person who usually commits changes to a project. He can start/stop builds, reorder builds in the build queue, label the build sources, review agent details. Agent Manager Agent Manager is a person responsible for customizing and managing the Build Agents. Project Viewer A Project Viewer has only read-only access for the projects the role is assigned to. Additionally, Project Viewer role does not have permissions to view agent details.
TeamCity Professional User Roles
The user roles in the TeamCity Professional Edition are not configurable.
Role Description Administrator TeamCity Administrators have no limitations in their permissions. They have access to all the projects, create users accounts, manage server licenses and set up projects and build configurations. User Common users correspond to "Project Developer" for all projects in the Enterprise edition. Users cannot create and edit projects and build configurations. Guest Guest users do not need any registration to access TeamCity. This role suits well for a non-committer who just monitors the projects status on the Projects page. The number of users, logged in to TeamCity simultaneously as guests, is not limited. In particular, guests can view all projects and build configurations but cannot customize the view of
Document generated by Confluence on Jun 16, 2008 13:43 Page 55 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 notification rules and receiving any notifications. • Reviewing Agent details
Document generated by Confluence on Jun 16, 2008 13:43 Page 56 RSS Feed
This page last changed on Nov 22, 2007 by mio. RSS Feed
TeamCity enables you to obtain information about the finished builds, or about the builds with the changes of particular users, via RSS feed. You can configure RSS feed from the TeamCity Tools sidebar of My Settings and Tools page, or from the home page of a build configuration. TeamCity produces a URL to the syndication feed on the base of the values, which you specify in the Feed URL Generator page.
See also:
• Concepts: Notifiers • UI Reference: Feed URL Generator • Working with Tools: Syndication Feed
Document generated by Confluence on Jun 16, 2008 13:43 Page 57 Run Configuration Policy
This page last changed on Nov 23, 2007 by mio. Run Configuration Policy
The run configuration policy allows you to select the specific build configurations you want a build agent to run. By default, build agents run all compatible build configurations and this isn't always desirable. The run configuration policy settings are located on the Compatible configurations tab of the Agent Details page.
See also:
• System Administrator Reference: Assigning Build Configurations to Specific Build Agents • UI Reference: Agent Details
Document generated by Confluence on Jun 16, 2008 13:43 Page 58 Security
This page last changed on May 04, 2008 by ivrina. Security
Security in TeamCity is handled by assigning different roles to users. Each role provides a set of permissions and is assigned (or not assigned) for each project, thus controlling access to the projects and the various features in the Web UI.
See also:
• Concepts: Permission | Role
Document generated by Confluence on Jun 16, 2008 13:43 Page 59 Supported Platforms and Environments
This page last changed on May 27, 2008 by yaegor. Supported Platforms and Environments
In this section:
• Platforms (Operating Systems) ° TeamCity Server ° Agents ° Windows Tray Notifier • Web Browsers • Build Runners ° For Java ° For .NET • Testing Frameworks • Version Control Systems • IDE Integration (plugin required) ° Eclipse ° IntelliJ IDEA ° Microsoft Visual Studio
Platforms (Operating Systems)
The TeamCity Server
The TeamCity server is platform independent.
Requirements:
• Java (JRE) 1.5+ (already included in Windows .exe distribution) • J2EE Servlet (2.4+) container, JSP 2.0+ container. TeamCity is tested under Tomcat 6 which is a recommended server. Tomcat 6 is already included in Windows .exe and .tar.gz distributions. TeamCity is reported to work with Jetty and Tomcat 5. Please note that Tomcat version 5.5.20 is not compatible with TeamCity because this version of Tomcat contains a number of bugs.
TeamCity server is tested under the following operating systems:
• Linux • MacOS X • Windows XP under Tomcat 6 web application server.
Reportedly works on:
• Solaris 10
Code Fragments Syntax Highlighting
The syntax highlighting (in the web difference view and Duplicates results) is available only under:
• Windows 32 bit platforms (workaround is available for Windows 64) • Linux 32 bit platforms Under other platforms the views will function normally, but the syntax highlighting will not be available.
Build Agents
Requirements:
Document generated by Confluence on Jun 16, 2008 13:43 Page 60 • Java (JRE) 1.5+ (already included in Windows .exe distribution; JDK (JRE is not enough) is necessary for IPR, Java Inspections and Duplicate Finder runners)
TeamCity agent is tested under the following operating systems:
• Linux • MacOS X • Windows 2000/XP/XP x64
Stop build functionality
Build stopping is supported on:
• Windows 2000/XP/XP x64 • Linux on x86, x64, PPC and PPC64 processors • Mac OS X on Intel and PPC processors • Solaris 10 on x86, x64 processors
The Windows Tray Notifier
• Windows 2000/XP Web Browsers
The TeamCity Web Interface is W3C complaint code, so just about any browser should work well with TeamCity. The following browsers have been specifically tested and reported to work correctly:
• Microsoft Internet Explorer 6 and 7 • Mozilla Firefox 2 and 3 beta 5 • Opera 9 • Safari 3 under Mac Build Runners
TeamCity provides a very wide of build tools support enabling both Java and .NET software teams building their projects.
Supported Java build runners:
• Ant 1.6-1.7 (TeamCity comes bundled with Ant 1.7.0) • Maven2 2.0.x (TeamCity comes bundled with Maven 2.0.8) • IntelliJ IDEA 5, 6 and 7 projects
Supported .NET platform build runners:
• MSBuild • NAnt (versions 0.85 - 0.86) • Microsoft Visual Studio Solutions (2003, 2005, and 2008) • Duplicates Finder for Visual Studio 2003, 2005 and 2008 projects (C# up to version 2.0 and Visual Basic .NET up to version 8.0) • Command Line Runner for running any build process by a command line
Rake runner is also supported by a plugin Testing Frameworks
• JUnit 3.8.1+, 4.x • NUnit • TestNG 5.3+
Document generated by Confluence on Jun 16, 2008 13:43 Page 61 Version Control Systems
Checkout on server
• Borland StarTeam 6 and up (StarTeam client application should be installed to use StarTeam integration) • CVS (client is bundled) • IBM Rational ClearCase, Base and UCM modes (ClearCase client should be installed to use ClearCase integration) • Microsoft Visual SourceSafe 6 and 2005 (SourceSafe client should be installed to use VSS integration) • Perforce (Perforce client should be installed to use Perforce integration) • Subversion (client is bundled) • Team Foundation Server 2005 and 2008 (TFS client should be installed to use TFS integration)
Checkout on agent
• CVS • Subversion
Creating a Label
• Borland StarTeam • CVS • Perforce • Subversion
IDE integration
TeamCity provides productivity plugins for the following IDEs:
• Eclipse 3.2, 3.3 • IntelliJ IDEA 6.0 (some functionality is limited) and 7.0 • Microsoft Visual Studio 2003, 2005, and 2008
Remote run and Pre-tested commit functionality is available for the following IDEs and version control systems:
IDE Supported VCS Eclipse • Subversion IntelliJ IDEA 6.0 and 7.0 • ClearCase • CVS • Perforce • StarTeam • Subversion • Visual SourceSafe MS Visual Studio 2003, 2005, 2008 • Subversion • Team Foundation Server External Databases
• HSQLDB • MySQL 5.0.30+ (Please note that due to bugs in MySQL at least versions 5.0.20 and 5.0.22 are not compatible with TeamCity) • PostgreSQL 8+ • Oracle 10g+
Document generated by Confluence on Jun 16, 2008 13:43 Page 62 TeamCity Data Directory
This page last changed on May 12, 2008 by pavel.sher. TeamCity Data Directory
This is the directory used by TeamCity to store configuration and system files. The config subdirectory contains the configuration of your TeamCity projects, and the system subdirectory contains build logs, artifacts, and database files (if HSQLDB is being used by default). See more on the directory structure in below.
Note that the system directory stores all the artifacts of the builds in the history and can be quite large (see Clean-Up Policy to configure how many builds are kept).
By default, the is placed in the user's home directory (e.g. it is $HOME/.BuildServer under Linux and C:\Documents and Settings\\.BuildServer) under Windows. Alternatively, you can define this directory in one of the following ways:
• as a Tomcat system property teamcity.data.path (see System Properties for Running the Server) • in the TEAMCITY_DATA_PATH environment variable (this will be used if the teamcity.data.path JVM system property is not found)
The TeamCity Windows installer can configure the TeamCity data directory during one of the installation steps.
If you run TeamCity as Windows service installed via standard procedure from the Windows executable file, you will need to modify the teamcity.data.path Tomcat JVM property as described in System Properties for Running the Server. Modifying the TEAMCITY_DATA_PATH environment variable will not work in this case.
The data directory used by the running TeamCity server can be looked up on the Administration > Server Configuration page.
Structure of TeamCity Data Directory
• .BuildServer/config — a directory where projects, build configurations and general server settings are stored. ° — configuration settings specific to a particular project - project-config.xml — main project configuration, contains configurations of a project's Build Configurations - project-config.xml.N — backup copies of project-config.xml created when a project's configuration is changed via web UI ° _trash — backup copies of deleted projects ° main-config.xml — server-wide configuration settings ° database.properties — database connection settings ° vcs-roots.xml — VCS roots configurations file (both shared and not shared) ° roles-config.xml — roles-permissions assignment file ° email-config.xml — the e-mail notification template ° jabber-config.xml — the Jabber notification template ° win32-config.xml — the Windows Tray Notifier notification template ° ide-notificator-config.xml — the IDE notification template
• .BuildServer/system — a directory where build results data are stored, namely: ° license.keys — a file which stores the license keys entered into TeamCity. ° responsibles.xml — a file which stores the "Take Responsibility" data. ° artifacts — a directory where the builds' artifacts are stored. The format of artifact storage is // ° messages — a directory where build logs are stored in internal format. ° changes — a directory where the remote run changes are stored in internal format. ° buildserver.* — a set of files pertaining to the embedded HSQLDB.
Document generated by Confluence on Jun 16, 2008 13:43 Page 63 ° version.dat — a file which contains the internal version of the configuration files and database. For backup purposes, ensure it is saved/restored in sync with other data files and the database data. ° sourcesCache — (Only in TeamCity 3.0.x) a directory with internal sources caches. Can be deleted any time to clear caches, they will be restored as needed. ° clearCaseCache — (Only in TeamCity 3.0.x) a directory with internal ClearCase sources caches. Can be deleted any time to clear caches, they will be restored as needed. ° caches — (Only in TeamCity 3.1) a directory with internal caches (of the VCS repository contents). It can be manually deleted to clear caches, they will be restored automatically as needed. Direct configuration files modifications
The files in the config directory can be edited manually. They can even be edited without stopping the server. TeamCity monitors these files for changes and rereads them automatically when modifications are detected. Bear in mind that it is easy to break the physical or logical structure of these files, so edit them with extreme caution. Always back up your data before making any changes.
Please note that there are interlinking entries that link by id. Examples of such entries are build configuration -> VCS roots links and VCS root -> project links. All the entries of the same type must have unique ids. New entries can be added only if their ids are unique. Please note that it is not a good idea to place TeamCity data directory to a network folder. Such folders may disappear if network failure occurs and TeamCity may decide that projects deleted and unload them. If you really need to place data directory to such folder, we strongly recommend to disable files modifications monitoring by launching TeamCity with special system property (available since 3.1.1): teamcity.configuration.checkInterval. Set this property to -1 to disable changes checking, positive value defines changes checking interval in seconds.
Document generated by Confluence on Jun 16, 2008 13:43 Page 64 Testing Frameworks
This page last changed on May 20, 2008 by ivrina. Testing Frameworks
TeamCity supports the following testing frameworks:
• JUnit and TestNG for the following runners: ° Ant ° Maven2 (when tests are run by Surefire Maven plugin) ° IntelliJ IDEA project (only JUnit tests are supported) • NUnit for the following runners: ° NAnt (nunit2 task) ° MSBuild (NUnit community or NUnitTeamCity tasks) ° Microsoft Visual Studio Solution runners (2003, 2005 and 2008)
TeamCity recognizes when a build performs tests, and reports the test results on-the-fly, without waiting for the build completion for all the above runners except Maven2. A failing test immediately manifests itself in the build state icon, and in the Tests tab of the Build results page, though the build goes on and performs the other tests (unless configured otherwise).
See also:
• Concepts: Build State | Build Runner • Administrator reference: .NET Testing Frameworks Support | Additional Functionality in MSBuild Scripts | NAnt • UI Reference: Tests tab
Document generated by Confluence on Jun 16, 2008 13:43 Page 65 User Account
This page last changed on Nov 26, 2007 by yaegor. Account
An account is a combination of a username and password that allows TeamCity users to log on to it and use its features.
The user accounts are assigned roles (a set of permissions) by the system administrator. The types of roles available depend on which TeamCity Edition (Professional or Enterprise) you have installed.
See also:
• Concept: Role | Permission • UI Reference: Server Configuration | User Accounts | Edit General Settings of the User
Document generated by Confluence on Jun 16, 2008 13:43 Page 66 VCS Root
This page last changed on Dec 27, 2007 by chamilton. VCS Root
VCS roots are a collection of VSC settings (paths to sources, login, password, and other settings) used by TeamCity to obtain the source files for your builds. The VCS roots are monitored by TeamCity, so that any changes uploaded to the version control system are shown in TeamCity's user interface. In many cases, you'll want to set up your build configuration to trigger a new build when TeamCity detects a user has made a change to any of the build configuration's VCS roots.
By default, VCS roots can be used by all of the project's build configurations. VCS roots can also be "shared", which means they also can be used by different projects in TeamCity.
For the VCS roots under ClearCase, CVS, Perforce, StarTeam and Subversion, TeamCity can label the source files of the builds. If VCS labeling is enabled, and the labeling format is defined on the Version Control Settings page, the labels appear in the build results page.
See also:
• Concepts: Version Control System • UI Reference: Version Control Settings | VCS Roots • Administrator's Reference: Configuring VCS Settings
Document generated by Confluence on Jun 16, 2008 13:43 Page 67 Version Control System
This page last changed on Feb 20, 2008 by chamilton. Version Control System
A Version Control System (VCS) is a system for tracking the revisions of the project source files. It is also known as SCM (source code management) or a revision control system.
TeamCity supports the following VCS:
• ClearCase • CVS • Perforce • StarTeam • Subversion • Team Foundation Server • Visual Source Safe
See also:
• UI Reference: Version Control Settings • Administrator's Reference: Configuring VCS Settings
Document generated by Confluence on Jun 16, 2008 13:43 Page 68 Developing TeamCity Plugins
This page last changed on May 04, 2008 by ivrina. Developing TeamCity Plugins
This is preliminary documentation and subject to change.
TeamCity is a highly extendable system. You can add various plugins in different places, including, but not limited to:
• Custom notifiers • Custom build triggers • Custom build runners with possibility to view customized reports on the Web • Extensions to Ant Runner which allows to add custom logging and view reports on the Web • Custom statistics reports based on the information in the database • Custom user authentication • Support of additional VCS
Currently, TeamCity can be extended on the build agent side, and on the server side (including web UI). Some extensions may require to extend TeamCity in all these places. We plan to provide a description for some typical plugins and how to write them.
The sources of the TeamCity OpenAPI are placed into the root directory of full TeamCity distribution (.tar.gz or .exe distribution) under the name openApi-source.jar.
TeamCity is compiled using JDK 1.5, so plugins should use JDK 1.5 as well.
Document generated by Confluence on Jun 16, 2008 13:43 Page 69 Agent Side Extensions
This page last changed on Apr 09, 2008 by ivrina. Agent-Side Extensions
Currently, there are two ways to extend build agent:
1. Write a custom build runner 2. Write an extension to AntRunner (for instance, to process custom tasks)
Both approaches use similar way of plugin packaging and deployment (see below). Descriptor
Plugin descriptor for the build agent plugins is named build-agent-plugin.xml. A build agent reads its plugins using NanoContainer:
Package your build agent plugin as a zip archive with the following content:
This archive will be unpackaged in the plugins subdirectory during the build agent installation: buildAgent/ buildAgent/bin/ buildAgent/lib/ buildAgent/plugins// buildAgent/plugins//lib/ buildAgent/plugins//otherDir/
Writing Ant Extension
Implement jetbrains.buildServer.agent.ant.AntTaskExtension interface and register it as a component in build-agent-plugin.xml file. Deployment
To deploy a build agent plugin:
1. Copy a build agent plugin's zip archive to the /update/plugins directory on the Team Server. 2. Copy server part of the plugin into the WEB-INF/lib directory of the Tomcat server. If server part was modified, restart Tomcat server. Agents will download updated plugin automatically.
Document generated by Confluence on Jun 16, 2008 13:43 Page 70 Plugin API FAQ
This page last changed on May 15, 2008 by lisar. Plugin API FAQ
What are basic entry points for TeamCity API?
See initial notes on Server Side Extensions and Typical Plugins pages.
How to create hooks for build start/fail/success and other events?
For a finished build, you can label sources using the SFinishedBuild:setLabel call. A list of VCS Roots can be created using the results of SBuild:getVcsRootEntries call.
Document generated by Confluence on Jun 16, 2008 13:43 Page 71 Server Side Extensions
This page last changed on Apr 21, 2008 by yaegor. Server-Side Extensions
Server-side plugin organization and deployment
To write a server-side plugin, you'll need to include jar libraries from /WEB- INF/lib directory to your classpath. Default TeamCity web application is "/webapps/ ROOT.
Server-side plugins are delivered as a set of jar files, one of which contains the plugin descriptor file. Such plugins can process data which is logged from build agents in some specific way, provide additional web content, create custom notifiers, etc.
The plugin code should be active - plugin components should register themselves in various TeamCity managers and components. Corresponding TeamCity managers should be passed via constructor (they will be passed by Spring framework via autowiring, see Descriptor section below)
If you are extending the Web UI, please also refer to Web UI Extensions.
Descriptor
The plugin descriptor file is named build-server-plugin-.xml and contains component definitions according to Spring configuration file syntax.
Base configuration of the server can be found in /WEB-INF/lib/server.jar!/META-INF/ buildServerSpring.xml and /WEB-INF/buildServerSpringWeb.xml files.
Example descriptor:
Deployment
Put the jar files with server side plugins into the /WEB-INF/lib/ directory on the server. Writing Server-side Extensions
Build server listeners
Should extend jetbrains.buildServer.serverSide.BuildServerListener interface and register itself using SBuildServer.addListener() method. There is also a convenient jetbrains.buildServer.serverSide.BuildServerAdapter class to write such listeners. public class MyListener extends BuildServerAdapter { public MyListener(SBuildServer server) { server.addListener(this); }
Document generated by Confluence on Jun 16, 2008 13:43 Page 72 // Your overridden methods go here }
Server-side extension points
TeamCity server has a number of extension points, where a plugin can provide some additional functionality. An extension point is defined in terms of interface, which extends jetbrains.buildServer.serverSide.ServerExtension. There are several such interfaces/extension points. To register an extension, a plugin should invoke method jetbrains.buildServer.serverSide.ServerExtensionHolder#registerExtension(extension_class, pluginCode, extensionObject).
Here is a list of some extension points:
• jetbrains.buildServer.serverSide.ParametersPreprocessor allows to modify build and run parameters which are sent to TeamCity server before build start • jetbrains.buildServer.serverSide.DataCleaner allows to register additional clean-up hooks for the case when build is removed • jetbrains.buildServer.serverSide.GeneralDataCleaner allows to register global additional cleanup procedures which are called once per cleanup • jetbrains.buildServer.serverSide.MainConfigProcessor allows to read/write global TeamCity data, which are saved in XML file main-config.xml • jetbrains.buildServer.serverSide.TextStatusBuilder allows to modify build status description line, like Tests passed: 343, Fitnesse: 23
Some core components jetbrains.buildServer.serverSide.SBuildServer
This is one of the core components of the TeamCity server-side support. It manages many aspects of TeamCity, for instance:
• Access to TeamCity installation information, system and configuration directories • Global TeamCity listener, which is notified about most events in TeamCity BuildServerAdapter • Global build history access via appropriate findNNN methods • Access to various TeamCity managers (but it is much better to use dependency injection provided by Spring to achive this, because these getXXXManager methods may disappear in the future) • Extension of TeamCity via various extension points, see ServerExtensionHolder (please also use DI) • TeamCity server version, build number • Executor service for short-time processes. jetbrains.buildServer.serverSide.ProjectManager
This component provides access to TeamCity project structure, allows to list all available projects and build configurations, as well as modify their settings. See also jetbrains.buildServer.serverSide.SProject and jetbrains.buildServer.serverSide.SBuildType jetbrains.buildServer.serverSide.RunningBuildsManager
Manager for currently running builds. See also jetbrains.buildServer.serverSide.SRunningBuild jetbrains.buildServer.serverSide.BuildHistory
Provides access to build history (you can also access historical builds for a build configuration using methods in jetbrains.buildServer.serverSide.SBuildType) jetbrains.buildServer.users.UserModel
Manager of various user-oriented operations in TeamCity, allows to list/find user accounts, create user accounts etc.
Document generated by Confluence on Jun 16, 2008 13:43 Page 73 jetbrains.buildServer.vcs.VcsManager
A basic starting point for various VCS-related operations, including, but not limited to:
• VcsSupport management (add your VCS support here!) • Obtain file contents • Create/Edit VCS root, check its status • Find committers between particular builds
Document generated by Confluence on Jun 16, 2008 13:43 Page 74 Statistics customization
This page last changed on May 04, 2008 by ivrina. Statistics customization
TeamCity provides number of ways to customize statistics. You can add your own custom metrics to integrate your tools/processes, insert any stats graph/report into any extension place, etc. Quick start
• TODO: how to use a plugin sample project, how to package and deploy a plugin (links?)
• Easy way to just insert jsp fragment into WebPlace — use a helper bean
• Easy way to add a custom build metric: Extend BuildValueTypeBase to just define your build metric calculation method, appearance and key - now you can reference this metric by its key in statistics chart/report tags More details
• Implement jetbrains.buildServer.serverSide.statistics.ValueType • Register it via jetbrains.buildServer.serverSide.statistics.StatsManager
Details on custom Build metrics
• Implement jetbrains.buildServer.serverSide.statistics.build.BuildFinishAware in your ValueType to be notified of build finished event • calculate your metric • Employ jetbrains.buildServer.serverSide.statistics.build.BuildDataStorage to publish your value • Employ jetbrains.buildServer.serverSide.statistics.build.BuildDataStorage to retrieve your dataset
Document generated by Confluence on Jun 16, 2008 13:43 Page 75 Typical Plugins
This page last changed on May 20, 2008 by lisar. Typical Plugins
In this section:
• Custom build number • Custom VCS • Custom Notifiers • Build Result Tabs • Custom User Authentication • Writing Custom Build Runner ° Agent-side Part ° Server-side Part
Custom build number public class MyBuildNumber extends BuildServerAdapter {
public MyBuildNumber(SBuildServer aBuildServer) { aBuildServer.addListener(this); }
public void buildStarted(SRunningBuild build) {
// Build Numbers set to "my" in build number pattern will be replaced with custom build number if ("my".equals(build.getBuildNumber())) { build.setBuildNumber(createBuildNumber(build)); } }
public String createBuildNumber(SRunningBuild build) { return "my custom#"; } }
Custom VCS
See jetbrains.buildServer.vcs.VcsManager.
If custom VCS plugin requires some settings to be edited from the web UI, then it should also provide a JSP file for its settings. This JSP file should be placed into the plugin jar under the buildServerResources/ path. In the buildServerSpring.xml you should also configure webResourcesUnpacker (note that you should use your vcs name as a plugin name), see above.
In the JSP file you should use special custom tags for input fields, radio buttons and checkboxes that correspond to your VCS properties. These custom tags are located in the props tag library:
Create subclass of ViewLogTab and attach it to the web place: WebControllerManager.addPageExtension(WebPlace.VIEW_LOG_TAB, this)
Custom User Authentication
Custom authentication API is based on Sun JAAS API. To provide your own authentication scheme, you should provide a login module class which must implement interface javax.security.auth.spi.LoginModule and register it in the jetbrains.buildServer.serverSide.auth.LoginConfiguration.
For example: public class CustomLoginModule implements javax.security.auth.spi.LoginModule { private Subject mySubject; private CallbackHandler myCallbackHandler; private Callback[] myCallbacks; private NameCallback myNameCallback; private PasswordCallback myPasswordCallback;
public void initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) { // We should remember callback handler and create our own callbacks. // TeamCity authorization scheme supports two callbacks only: NameCallback and PasswordCallback. // From these callbacks you will receive username and password entered on the login page. myCallbackHandler = callbackHandler; myNameCallback = new NameCallback("login:"); myPasswordCallback = new PasswordCallback("password:", false); // remember references to newly created callbacks myCallbacks = new Callback[] {myNameCallback, myPasswordCallback};
// Subject is a place where authorized entity credentials are stored. // When user is successfully authorized, the jetbrains.buildServer.serverSide.auth.ServerPrincipal // instance should be added to the subject. Based on this information the principal server will know a real name of // the authorized entity and realm where this entity was authorized. mySubject = subject; }
public boolean login() throws LoginException { // invoke callback handler so that username and password were added // to the name and password callbacks try { myCallbackHandler.handle(myCallbacks); } catch (Throwable t) { throw new LoginException(t.toString()); }
// retrieve login and password final String login = myNameCallback.getName(); final String password = new String(myPasswordCallback.getPassword());
// perform authentication
Document generated by Confluence on Jun 16, 2008 13:43 Page 77 if (checkPassword(login, password)) { // create ServerPrincipal and put it in the subject mySubject.getPrincipals().add(new ServerPrincipal(null, login)); return true; }
public boolean abort() throws LoginException { return true; }
public boolean logout() throws LoginException { return true; } }
Now we should register this module in the server. To do so, we create a login module descriptor: public class CustomLoginModuleDescriptor implements jetbrains.buildServer.serverSide.auth.LoginModuleDescriptor { // Spring framework will provide reference to LoginConfiguration when // the CustomLoginModuleDescriptor is instantiated public CustomLoginModuleDescriptor(LoginConfiguration loginConfiguration) { // register this descriptor in the login configuration loginConfiguration.registerLoginModule(this); }
public Class getLoginModuleClass() { // return our custom login module class return CustomLoginModule.class; }
public Map getOptions() { // return options which can be passed to our custom login module // for example, we could store reference to SBuildServer instance here return null; }
public String getTextForLoginPage() { // return text to show on the login page which could describe // what should be entered in the user name and password fields return null; }
public String getDisplayName() { // presentable name of this plugin return "My custom authentication plugin"; } }
Finally we should create build-server-plugin-ourUserAuth.xml as it is described above and write there CustomLoginModuleDescriptor bean:
Document generated by Confluence on Jun 16, 2008 13:43 Page 78
Create a jar, put it into the WEB-INF/lib directory of the TeamCity server and restart it. When the server is started, you should be able to choose your custom plugin from the drop down list of the Administration -> Server Configuration page.
Writing a Custom Build Runner
Agent-side Part
Implement jetbrains.buildServer.agent.BuildRunner interface (you may also extend GenericProgramRunner or even JavaProgramRunner helpers for this). To log your messages, you may obtain instance of ServerLogger singleton (you may also use ServerLoggerFacade for convinience).
TBD
Server-side Part
Build agent plugin should also provide server side jar with a class implementing jetbrains.buildServer.serverSide.RunType interface. The implementation of the RunType interface must be registered in the jetbrains.buildServer.serverSide.RunTypeRegistry. You can do this in the constructor of the RunType implementation, like this: public class CustomRunTypeImpl { ... public CustomRunType(RunTypeRegistry runTypeRegistry) { runTypeRegistry.registerRunType(this); } ... }
Please note that you should also provide the plugin descriptor file named build-server-plugin- .xml which will contain reference to the RunType implementation:
Document generated by Confluence on Jun 16, 2008 13:43 Page 79 Web UI Extensions
This page last changed on Apr 11, 2008 by ivrina. Web UI Extensions
Web resources (jsp, css, js, etc) should be placed into the plugin jar file under the path buildServerResources/. After that you should register this jar in the WebResourcesManager. This should be done while Spring is creating objects (i.e. in the plugin constructor). For example: public class MyPlugin { public MyPlugin(WebResourcesManager resourcesManager) { resourcesManager.addPluginResources("myPlugin", "myPlugin.jar"); } }
Plugin jar should be placed into the /WEB-INF/lib/ directory. Resources like buildServerResources/ file.js will be unpacked under the name /plugins/aPluginName/file.js. You can obtain this path with help of WebResourcesManager.resourcePath() method.
Document generated by Confluence on Jun 16, 2008 13:43 Page 80 Installation and Upgrade
This page last changed on Nov 07, 2007 by mio. Installation and Upgrade
In this part you will learn how to install and upgrade TeamCity.
• Installation • Migrating to an External Database • Setting up an External Database • TeamCity Data Backup • Upgrade • Upgrade Notes
Document generated by Confluence on Jun 16, 2008 13:43 Page 81 Installation
This page last changed on Feb 12, 2008 by chamilton.
Installation
Obtaining TeamCity
TeamCity installation package is identical for both Professional and Enterprise Editions and is available at http://www.jetbrains.com/teamcity/download/index.html
Download one of the three available installation packages:
Target Download Note Windows TeamCity.exe Executable Windows installer bundled with Tomcat and Java 1.5 JRE Linux, MacOS X TeamCity.tar.gz Package bundled with Tomcat servlet container for Linux, MacOS X or manual installation J2EE container TeamCity.war Package for installation into an existing J2EE container
Installing the TeamCity Server
Follow the environment specific instructions on Installing and Configuring the TeamCity Server.
Larger development teams, which run frequent builds are recommended to reduce the load on the TeamCity server by disabling the default build agent service on the server. These teams will need to install additional build agents (see below).
Installing Additional Build Agents
Follow the instructions on Setting up and Running Additional Build Agents.
See also
• Installation: Installing and Configuring the TeamCity Server | Setting up and Running Additional Build Agents
Document generated by Confluence on Jun 16, 2008 13:43 Page 82 Installing Additional Plugins
This page last changed on Apr 21, 2008 by yaegor. Installing Additional Plugins
For a list of available plugins, see plugins list
Installing jar-packaged server-side plugin
1. Shutdown TeamCity server 2. Copy the plugin jar file into /WEB-INF/lib directory. Default TeamCity web application is /webapps/ROOT. 3. If the plugin requires any libraries, copy them into /WEB-INF/lib directory also. 4. Start TeamCity server.
Installing agent-side plugin
• Copy the agent plugin into /WEB-INF/update directory.
All the agents will be upgraded automatically. No agent or server restart is necessary.
Document generated by Confluence on Jun 16, 2008 13:43 Page 83 Installing and Configuring the TeamCity Server
This page last changed on May 08, 2008 by yaegor. Installing and Configuring the TeamCity server
In this section:
• Installing the TeamCity Server • Configuring the TeamCity Server Installing the TeamCity Server
Having obtained the TeamCity installation package, proceed with installing the build server for:
• Windows .exe distribution • .tar.gz distribution • .war distribution
The build server and one build agent will be installed by default for Windows, Linux or MacOS X. If you need more build agents, refer to the section Installing Additional Build Agents. By default, TeamCity uses an HSQLDB database that does not require special configuring. This database works fine for testing and evaluating the system. For production purposes using a standalone external database is recommended.
• Setting up an External Database • Migrating to an External Database
Installing TeamCity via executable file (Windows only)
For the Windows platform, run the executable file and follow the installation instructions. You have options to install the TeamCity web server and one build agent that can be run as a Windows service.
If you opted to install the services, use standard Windows Services applet to manage the service. The server can also be started/stopped with the help of provided scripts#runStopServer.
If you want to edit the TeamCity server's service parameters, memory settings or system properties after the installation, run the command '/bin/tomcat6w.exe //ES//TeamCity' and modify Java Options under the Java tab. more information Service account
Please make sure the service account has:
• write rights for the TeamCity Data Directory, • all the necessary permissions to work with the source controls used. This includes: ° access to Microsoft Visual SourceSafe database (if Visual Source Safe integration is used). ° the user, under which TeamCity server service runs, and ClearCase view owner are the same (if ClearCase integration is used).
By default, Windows service in installed under SYSTEM ACCOUNT. To change it, use the Services applet (Control Panel | Administrative Tools | Services)
Installing TeamCity bundled with Tomcat servlet container (Linux, Mac OS X, Windows)
Unpack TeamCity.tar.gz archive (for example, using tar xfz TeamCity.tar.gz command under Linux, or WinZip, WinRar or alike utility under Windows).
Document generated by Confluence on Jun 16, 2008 13:43 Page 84 Please use GNU tar to unpack. (e.g. Solaris 10 tar is reported to truncate too long file names and may cause a ClassNotFoundException. Consider getting GNU tar at Solaris packages or using gtar xfz command)
TeamCity server can be started and stopped by the scripts provided in the /bin directory To start/stop TeamCity server and default agent at the same time use runAll script. To start/stop only the TeamCity server use teamcity-server script (available since TeamCity 3.1). e.g. use runAll.bat start to start the server and the default agent, and use runAll.bat stop to stop the server and the default agent
By default, TeamCity runs on http://localhost:8111/ and has one registered build agent that runs on the same computer.
The port number can be edited in the /conf/server.xml file, line
Headless mode for TeamCity If you are running TeamCity on a server that is not running a windowing system, e.g. Linux, then you may encounter this error when hitting the Statistics page:
javax.el.ELException: Error reading 'graphInfo' on type jetbrains.buildServer.serverSide.statistics.graph.BuildGraphBean
You can resolve this problem by adding this to your catalina.sh file:
JAVA_OPTS="-Djava.awt.headless=true"
Alternatively, you can add it to a new setenv.sh file that sits in your bin directory. The same can be applied to any start up script if you are using an third party container.
Installing TeamCity into existing J2EE container
1. Copy the downloaded TeamCity.war file into the web applications directory of your J2EE container under teamCity.war name. 2. To configure TeamCity logging system, modify J2EE container settings to pass the following JVM options to the TeamCity web application:
Up to date values and conf/teamcity-server-log4j.xml file can be looked up in the bin/teamcity- server script available in .exe and tar.gz distributions. Sample teamcity-server-log4j.xml file.
1. Ensure TeamCity web application can use at least 512Mb heap size and 96Mb of PermGen size (usually, this is done by specifying JVM options -Xmx512m -XX:MaxPermSize=128m). Please increase the sizes if you have other web applications running in the same JVM. 2. Restart the server or deploy the application via servlet container administration interface and access http://server/teamCity/.
TeamCity J2EE container distribution is tested to work with Tomcat 6.x servlet container. (Tomcat version 5.5.20 is not compatible with TeamCity because this version of Tomcat contains a number of errors) Configuring the TeamCity Server
Tips
• If you have a lot of projects or build configurations, we recommend you avoid using the Default agent in order to free up the TeamCity server resources. The TeamCity Administrator can disable the default agent on the Agents page of the web UI.
Document generated by Confluence on Jun 16, 2008 13:43 Page 85 • When changing the TeamCity data directory or database make sure they do not get out of sync.
Configuring TeamCity data directory
The default placement of the TeamCity data directory can be changed. See corresponding section: TeamCity Data Directory for details.
Edit server configuration
• Accessing Server from Scripts • Authentication Settings • Build Script Interaction with TeamCity • Changing user password with default authentication scheme • Configuring Server URL • Configuring UTF8 Character Set for MySQL • Enabling Guest Login • Including Third-Party Reports in the Build Results • Mapping External Links in Comments • Using HTTPS to access TeamCity server
See also:
• Installation: Setting up and Running Additional Build Agents
Document generated by Confluence on Jun 16, 2008 13:43 Page 86 Setting up and Running Additional Build Agents
This page last changed on May 19, 2008 by yaegor.
Error formatting macro: toc: java.lang.NullPointerException Setting up and Running Additional Build Agents
Before you can start customizing projects and creating build configurations, you need to configure build agents.
Note If you install TeamCity bundled with a Tomcat servlet container, or opt to install an agent for Windows, both the server and one build agent are installed. This is not a recommended setup for production purposes, since the build procedure can slow down the responsiveness of the web UI and overall TeaMCity server functioning. If you need more build agents, perform the procedure described below.
To install a build agent, follow these general steps:
1. Open the Agents tab 2. Click the Install Build Agents link located in the top-right area of the page 3. In the Install Build Agents pop-up, choose one of the available installation options: • using Java Web Start • using MS Windows installer • manually via zip file 4. When an agent connects to the server for the first time, it appears on the Unauthorized agents tab under Agents, where administrators can authorize it. This will connect it to the server for the first time. Agents will not run builds until they are authorized and enabled. The agent running on the same computer as the server is authorized and enabled by default.
Please note that in order to run a TeamCity agent, the user under which account the agent runs, should have the following privileges:
• Log on as a service (to run as Windows service) • Start/Stop service (to run as Windows service, necessary for agent upgrade to work) • Debug programs (for take process dump functionality to work) • have write access to following directories: , , and
Installing Build Agents via Java Web Start
1. Make sure JDK 1.5+ is installed on the computer. 2. On the agent computer, set up the JAVA_HOME environment variable to point to the JDK 1.5+ installation directory. 3. Navigate to the Agents tab in the TeamCity web UI. 4. Click the "Install Build Agents" link and then click "Via Java Web Start". 5. Follow the instructions. Note You can install the build agent Windows service during the installation process or manually.
Installing Build Agents via a MS Windows installer
Run the agentInstaller.exe Windows Installer and follow the installation instructions.
Installing Build Agents via a zip file
1. Unzip the downloaded file into the desired directory.
Document generated by Confluence on Jun 16, 2008 13:43 Page 87 2. Make sure that you have a JDK or JRE installed (You will need JDK (not JRE) for some build runners like Ipr runner, Inspections, and Duplicates). Please ensure that the JRE_HOME or JAVA_HOME environment variables are set (pointing to the installed JRE or JDK directory respectively) for the shell in which the agent will be started. 3. Navigate to the \conf directory, locate the file called buildAgent.dist.properties and rename it to buildAgent.properties. 4. Edit the buildAgent.properties file and change the properties of the installed build agent: • serverUrl - URL of the TeamCity server (the one used to open web TeamCity UI). • name - name of the build agent that will be visible in the web UI. All agents connected to TeamCity server must have unique names. • ownPort - (not required) port number that agent use to accept connections from server. Please make sure there is no firewall blocking incoming connections to the port. The port must not be used by any other application installed on the computer. If you want to install several build agents on the same computer, make sure they are assigned different ports. • ownAddress - (not required) the IP address of the computer running build agent. Required only if automatic detection fails (e.g. if there are several network interfaces on the computer). 5. Under Linux, you may need to give execution permissions to the bin/agent.sh shell script. Note On Windows you may also want to install the build agent windows service instead of manual agent startup.
Starting the Build Agent
To start the agent manually, run the following script:
• for Windows: \bin\agent.bat start • for Linux and MacOS X: \bin\agent.sh start If you're running build agent on MacOS X and you're going to run Inspection builds, you may need to use the StartupItemContext utility:
To stop the agent manually, run the \agent script with a stop parameter.
Use stop to request stopping after current build finished. Use stop force to request immediate stop (if a build is running on the agent, it will be stopped abruptly (canceled)) Under Linux, you have one more option top use: stop kill to kill the agent process.
If the agent runs with a console attached, you may also press Ctrl+C in the console to stop the agent (if a build is running it will be canceled).
Installing and Running a Build Agent as a Windows Service
In Windows, you may want to use the build agent Windows service to allow the build agent to run without any user logged on.
Note to people upgrading from version 1.2
Since version 1.2, Build Agents are using a new Windows Service Library: Java Service Wrapper. The old service name, agentd, is no longer used in fresh installations. Agents that were already installed will continue to use old service until explicit installation. (more information)
To install the service:
Document generated by Confluence on Jun 16, 2008 13:43 Page 88 1. Make sure there is no TeamCity Build Agent Service or agentd service already installed. 2. Run the /bin/service.install.bat file.
To start the service:
• Run /bin/service.start.bat
To stop the service:
• Run /bin/service.stop.bat
The new service wrapper allows to change agent JVM parameters via standard way of Java Service Wrapper library. The configuration is located at \launcher\conf\wrapper.conf
The agent process name is TeamCityAgentService-windows-x86-32.exe. To work with net.exe utility, use TCBuildAgent name. For example:
net start TCBuildAgent
Service system account
To run builds, the build agent should be started under a user with enough rights for performing a build. By default, Windows service in started under SYSTEM ACCOUNT. To change it, use the Services applet (Control Panel|Administrative Tools|Services)
Installing Several Build Agents on the Same Machine
Several agents can be installed on a single machine. They function as separate agents and TeamCity works with them as different agents, not utilizing the fact that they share the same machine. After installing one agent you can install additional one, providing the following conditions are met:
• the agents are installed in the separate directories • they have distinctive "work" and "temp" directories • buildAgent.properties is configured to have different values for name and ownPort properties
Make sure, there are no build configurations that have absolute checkout directory specified (alternatively, make sure, such build configurations have "clean checkout" option turned ON.
Under Windows, to install the additional agents as services, modify \launcher \conf\wrapper.conf to change wrapper.console.title, wrapper.ntservice.name, wrapper.ntservice.displayname and wrapper.ntservice.description properties to have distinct name within the machine. See also
• Concepts: Build Agent • UI Reference: Agents
Document generated by Confluence on Jun 16, 2008 13:43 Page 89 Migrating to an External Database
This page last changed on May 15, 2008 by ivrina. Migrating to an External Database
By default, TeamCity runs using an internal database that uses the HSQLDB database engine. The internal database suits evaluation purposes since it works out of the box and requires no additional setup. However, we strongly recommend using an external database as a back-end TeamCity database in a production environment.
TeamCity 3.1 supports MySQL, Oracle, and PostgreSQL external databases.
Please refer to Setting up an External Database page for the database-specific configuration steps. If you want to start using external database from the first TeamCity start, these are the only steps you need.
If you were using TeamCity with the internal storage engine, there are two ways to switch to an external database:
• Switch with no data migration: build configurations settings will be preserved, but not the historical builds data or users. • Full Migration: all the data is preserved except Inspections and Duplicate build results (and any database-stored data provided by the third-party plugins). Database migration cannot be combined with server upgrade. If you want to upgrade at the same time, you should first upgrade (run the new version of TeamCity) and then migrate to another database. Switching to another database
To switch to another database without saving the build history or user data:
1. Install and set up an external database. 2. Shut down the TeamCity server. 3. Create a backup copy of the used by the server 4. Clean up the system folder: you must remove messages and artifacts folders from /system folder of your ; you may delete old HSQLDB files: buildserver.* to remove the no longer needed internal storage data. 5. Start the TeamCity server.
Full Migration
Please note that significant migration improvements were introduced between versions 3.0 in 3.1. Refer to the applicable description: 3.0 or 3.1.
This section provides descriptions of TeamCity migration to different types of external databases:
• Full Migration in TeamCity 3.0 • Full Migration in TeamCity 3.1
Full Migration in TeamCity 3.0
TeamCity 3.0.x supports migration only to MySQL database.
The target database must be empty before the migration process (it should NOT contain any tables).
To migrate all your existing data to an external database:
1. Shut the TeamCity server down. 2. Create a backup copy of the used by the server.
Document generated by Confluence on Jun 16, 2008 13:43 Page 90 3. Download the MySQL JDBC driver from: http://dev.mysql.com/downloads/connector/j/. 4. Place the MySQL driver into the TeamCity WEB-INF/lib folder. Further instructions assume the driver is named mysql-connector-java-5.0.5-bin.jar. 5. Run the export/import tool. 6. Move database.properties file to the config folder of your . This file is created when the database migration is successfully finished. 7. Copy a proper version.dat file to the system folder of your , overwriting the existing file. This file is also created when the migration is successfully finished. 8. Start the TeamCity server.
Running the Export/Import Tool
To start the export/import tool use the following commands from the TeamCity WEB-INF/lib folder:
• For Windows: You may use a command-line script that will perform a number of steps for you. To use it, navigate to the \bin directory, execute the migrateToMySQL.bat file, and follow the prompts. Alternatively, you can run the export/import tool manually:
SET CP=server.jar;openapi.jar;server-openapi.jar;mysql-connector-java-5.0.5- bin.jar;hsqldb.jar;dbunit-2.2.jar;common.jar;server-model.jar;log4j-1.2.12.jar;jdom.jar
Depending on the location of your TeamCity data path there are three different sets of arguments to use with the export/import tool: • For the default location of the (i.e. /.BuildServer) use:
Document generated by Confluence on Jun 16, 2008 13:43 Page 91 Thu Apr 05 12:46:03 MSD 2007 Initializing schema... TABLES to be converted: (29) [agent, agent_sources_version, ....] Thu Apr 05 12:46:09 MSD 2007 Exporting data to C:\TEMP\TC-export56020 Thu Apr 05 12:46:10 MSD 2007 Importing data from C:\TEMP\TC-export56019 Thu Apr 05 12:46:13 MSD 2007 Exporting database.properties Thu Apr 05 12:46:13 MSD 2007 Exporting version.dat Thu Apr 05 12:46:13 MSD 2007 Done.
Additional information
• MySQL JDBC URL format:
jdbc:mysql://[:]/
Refer to this page for more information. • If you encounter an "out of memory" error, try increasing the number in the -Xmx512m parameter. On a 32-bit platform the maximum is about 1300 megabytes
Full Migration in TeamCity 3.1
TeamCity 3.1 supports HSQLDB, MySQL, Oracle, and PostgreSQL; the migration tool can move data between any of these databases.
Support of Microsoft SQL Server 2005 is also included in TeamCity 3.1, but it has "experimental" status.
The target database must be empty before the migration process (it should NOT contain any tables).
To migrate all your existing data to a new external database:
1. Set up an external database to be used by TeamCity. You can refer to Setting up an External Database for information on how to set up a TeamCity-specific. (At this point you should only create and configure the database, do not modify any TeamCity settings at this time). 2. Shut the TeamCity server down. 3. Create a backup copy of the used by the server 4. If the database driver is not bundled with TeamCity (refer the database properties table below, and place the appropriate driver into the TeamCity WEB-INF/lib directory. The following instructions refer to the driver as . 5. Edit the /bin/dbMigration.properties file, entering correct values for the source and target database. Ensure all the properties are supplied and only the necessary lines are uncommented (single-line comments are designated by # character) 6. Run the migration tool (see below) 7. Upon the successful completion of the database migration, a database.properties file will be created. Move this file into the config folder of your (this step is performed automatically by the migrateDB script) 8. Additionally a version.dat file will be created. Copy it to system folder of your , overwriting the existing file (this step is performed automatically by the migrateDB script) 9. Start TeamCity server. This should be the same TeamCity version that was run last time (TeamCity upgrade should be performed as a separate procedure).
Databases Properties Table
Sample dbMigration.properties file residing in the bin directory contains sections for several databases. DB Name Driver Class Name Driver jar Name Driver is Bundled JDBC URL format MySQL com.mysql.jdbc.Drivermysql-connector- no, download page jdbc:mysql:// java-5.0.8-bin.jar [:]/
Document generated by Confluence on Jun 16, 2008 13:43 Page 92 PostgreSQL org.postgresql.Driverpostgresql-8.2-505.jdbc3.jaryes jdbc:postgresql:// [:]/ Oracle oracle.jdbc.driver.OracleDriverojdbc14.jar no, download page jdbc:oracle:thin:@:: HSQLDB org.hsqldb.jdbcDriverhsqldb.jar yes jdbc:hsqldb:hsql:// [:]/
Running the Migration Tool
You can use the migrateDB.bat/migrateDB.sh script located in the \bin directory. Just run the script and follow the instructions.
Generally, you would need to run the script with single migrate parameter to perform the migration and move the generated configuration files into .
Additional information
• If you encounter an "out of memory" error, try increasing the number in the -Xmx512m parameter in the migrateDB script. On a 32-bit platform the maximum is about 1300 megabytes.
Alternative approach is to run HSQLDB in standalone mode via java -Xmx256M -cp ..\webapps\ROOT\WEB-INF\lib\hsqldb.jar org.hsqldb.Server -database.0 \system\buildserver -dbname.0 buildserver and then running the Migration tool pointing to the database as the source: jdbc:hsqldb:hsql:// localhost/buildserver sa ''
See also:
• Concepts: TeamCity Data Directory • Installation and Upgrade: TeamCity Data Backup | Setting up an External Database
Document generated by Confluence on Jun 16, 2008 13:43 Page 93 Setting up an External Database
This page last changed on Jun 06, 2008 by yaegor. Setting up an External Database
TeamCity 3.0 supports MySQL and PostgreSQL. Oracle support was added in TeamCity 3.1.
This document covers external database setup for the first use with TeamCity. If you evaluated TeamCity with internal database and want to preserve the data while switching to an external database, please refer to Migrating to an External Database guide.
In this section: Setting up MySQL Setting up PostgreSQL Setting up Oracle General Steps
1. If you already ran TeamCity but do not want to preserve any data, delete TeamCity Data Directory. All the data you entered into TeamCity will be lost. To preserve your data refer to the migration guide. 2. Run TeamCity with the default settings to create the . 3. Shutdown the TeamCity server. 4. Perform database-specific steps described below for MySQL, PostgreSQL or Oracle. 5. Start server.
Please note that TeamCity actively modifies its own database schema. The user account used by TeamCity should have permissions to create new, modify and delete existing tables in its schema, in addition to usual read/write permissions on all tables.
Setting up MySQL
1. Download the MySQL JDBC driver from: http://dev.mysql.com/downloads/connector/j/ 2. Put MySQL connector jar to the WEB-INF/lib directory of TeamCity web application 3. Create an empty database for TeamCity in MySQL and grant permissions to modify this database to a user from which TeamCity will work with this database. We recommend using UTF-8 character set for the database. Please consult this document for more details on how to create database with Unicode support. 4. In the /config folder rename database.mysql.properties file to database.properties and specify the required settings in this file:
1. Create an empty database for TeamCity in PostgreSQL and grant permissions to modify this database to a user from which TeamCity will work with this database. Be sure to set up it to use UTF8. 2. In the /config folder create file database.properties and specify the required settings in this file:
Document generated by Confluence on Jun 16, 2008 13:43 Page 94 driverName=org.postgresql.Driver connectionUrl=jdbc:postgresql:/// connectionProperties.user= connectionProperties.password= maxConnections=50 poolPreparedStatements=true
Setting up Oracle
Supported Oracle versions: 10g+
Oracle support is available only since TeamCity 3.1
1. Download the Oracle JDBC Thin driver from: http://www.oracle.com/technology/software/tech/java/ sqlj_jdbc/htdocs/jdbc_10201.html 2. Put the driver jar (ojdbc14.jar) into the WEB-INF/lib directory of TeamCity web application 3. Create TeamCity user in Oracle database and grant permissions to modify this database to a user from which TeamCity will work with this database. 4. In the /config folder create file database.properties and specify the required settings in this file:
• Installation and Upgrade: Migrating to an External Database
Document generated by Confluence on Jun 16, 2008 13:43 Page 95 TeamCity Data Backup
This page last changed on Apr 29, 2008 by ivrina. TeamCity Data Backup
We strongly urge you to make the backup of TeamCity data before making any upgrade. Please note that TeamCity server does not support downgrading. Server Backup
Before performing the backup procedures, you need to stop the TeamCity server.
The following is needed to be backed up:
1. You may refer to TeamCity Data Directory section on the directory structure. Please note that you need to always back up the /system/ version.dat file, and ensure it is saved/restored in sync with other data files and the database data.
The /system/buildserver.* files store HSQLDB data. You should back them up if you use HSQLDB (a default setting). 2. Database data Database stores all information on the build results (except for artifacts and build logs), VCS changes, pinned builds, agents, build queue, user accounts, etc. • If you use HSQLDB (default, not recommended for production), the database is stored in the /system folder. All files from the directory can be backed up. Or refer to the HSQLDB backup notes. • If you use MySQL, please back up your database schema used by TeamCity. MySQL database connection settings are specified in the / config/database.properties file. See also corresponding installation section. 3. Application files You do not need to back up TeamCity application directory (web server alone with the web application), provided you still have original distribution package and you didn't: • place any custom libraries for TeamCity to use • install any non-default TeamCity plugins • make any startup script/configuration changes If you feel you need to back up the application files: • If you use non-war distribution: back up everything under except for temp and work directories. • If you use war distribution, pursue the backup procedure of the servlet container used. 4. Log files If you need TeamCity log files (which are mainly used for problem solving or debug purposes), back up /logs directory. You may also want to back up TeamCity Windows Service settings, if they were modified.
Build Agent's Data Backup
1. Build Agent configuration Back up the /conf/buildAgent.properties file. You may also wish to back up any other configuration files changed (Build Agent configuration is specified in /conf and /launcher/conf directories). 2. Log files If you need Build Agent log files (mainly used for problem solving or debug purposes), back up /logs directory. You may also wish to back up Build Agent Windows Service settings, if they were modified.
Document generated by Confluence on Jun 16, 2008 13:43 Page 96 Upgrade
This page last changed on May 04, 2008 by ivrina. Upgrading TeamCity
In this section: Upgrading the TeamCity Server
• Using a Windows Installer • Using a war or zip distribution package
Upgrading Build Agents
• Upgrading the Build Agent to 3.0 • Automatic Build Agent Upgrading Please back up your data before any upgrade and review the Upgrade Notes.
Licensing Issues
Upgrades to TeamCity versions up to versions 3.x are free of charge. Please note that TeamCity 3.x uses new licensing policy comparing to that of previous TeamCity versions. Please review the new Licensing Policy.
Upgrading Using a Windows Installer
1. Shut the server down. 2. Shut the agent down if it was installed from the TeamCity installation package. 3. Locate the .BuildServer folder on the disk and create a backup of this folder (usually this folder is created in the home directory of the user under which the TeamCity server is running). 4. Back up the configuration files in the TeamCity installation folder if you modified them or installed custom plugins. If you are upgrading from TeamCity 1.x, it is recommended to move your database settings from the /ROOT/WEB-INF/buildServerSpring.xml file in your backup to the database.properties file located in the TeamCity configuration data directory (/config). 5. Uninstall the previous installation using Add or Remove Programs. 6. Run the new installer. When prompted, specify the used by previous installation. 7. If you use an external database put the appropriate driver jar into the /ROOT/WEB-INF/lib directory. Refer to the following database properties table for more information. 8. If you use custom plugins, put their jars into /ROOT/WEB-INF/ lib for server-side plugins and into /ROOT/update/plugins for build agent plugins. 9. Start up the TeamCity server (and agent if it was installed together with the installer). 10. If your project contains build configurations related to *.ipr and inspections, you are required to update and correct the build configuration settings. To do it, visit the build configuration page/ build runner section. The first visit to this page may take time, because TeamCity will download and analyze all the project module (*.iml) files to detect which global libraries, path variables, jdk, etc. are used. Subsequent visits will be much faster. Review the settings and make sure that all the settings are correct. Manual Upgrading on Linux and for WAR Distributions
1. Shut the server down. 2. Locate the on the disk and create a back up of this folder (usually this folder is created in the home directory of the user under which the TeamCity server is running).
Document generated by Confluence on Jun 16, 2008 13:43 Page 97 3. Back up old TeamCity files (either the whole TeamCity directory or [TOMCAT_HOME]/webapps/ TeamCity/* if you are installing from a war file). If you are upgrading from TeamCity 1.x, it is recommended to move your database settings from the WEB-INF/buildServerSpring.xml file in your backup to the database.properties file located in the TeamCity configuration data directory (/ config). 4. Remove old installation files (either the whole TeamCity directory or [TOMCAT_HOME]/webapps/ TeamCity/* if you are installing from a war file). 5. Unpack the new archive where TeamCity was previously installed. 6. If you use an external database put the appropriate driver jar into the WEB-INF/lib directory. Refer to the following database properties table for more information. 7. If you use custom plugins, put their jars into ROOT/WEB-INF/lib for server-side plugins and into ROOT/update/plugins for build agent plugins. 8. Specify additional System Properties for Running the Server, if required. 9. Start up the TeamCity server. 10. If your project contains build configurations related to *.ipr and inspections, it is required to update and correct build configuration settings. To do it, visit the build configuration page/build runner section. The first visit to this page may take time, because TeamCity will download and analyze all project module (*.iml) files to detect used global libraries, path variables, jdk and so on. Subsequent visits will be much faster. Look through the settings and make sure that all settings are correct.
All the configuration data and database scheme will by updated by our converters upon the first startup after the upgrade.
Upgrading Build Agents to 3.0
When upgrading to TeamCity 3.0 for the first time there are two parts of the agent that need to be upgraded manually: the Windows service wrapper and the agent launcher. The easiest way to upgrade an agent is uninstall current build agent and then install the newer one.
Upgrading Build Agent Launcher
You only need to perform this step if you do not want to uninstall and then install the agent again, which is the preferred way of agent upgrade.
Agent launcher is the process that is first started for the agent and manages other child processes that actually connect to the server and perform the build.
1. Wait till agent is upgraded automatically. 2. Check \lib\latest folder. If it does not exist, no further steps are needed, you have the latest launcher version installed. 3. Stop agent. 4. Move content of the \lib\latest folder to the \lib folder, overwriting existing files, if needed. 5. Start the agent.
Upgrading the Build Agent Windows Service Wrapper
Upgrading from TeamCity version 1.x
Version 2.0 of TeamCity migrated to new way of managing Windows service (service wrapper) for the build agent: Java Service Wrapper library.
One of advantages of using new service wrapper is ability to change any JVM parameters of the build agent process.
1.x versions installed Windows service under name agentd, while 2.x versions use TeamCity Build Agent Service name.
Document generated by Confluence on Jun 16, 2008 13:43 Page 98 The service wrapper will not be migrated to new version automatically. You do not need to use the new service wrapper, unless you need its functionality (like changing agent JVM parameters).
To use new service wrapper you should uninstall old version of the agent (with Control Panel | Add/ Remove Programs) and then install a new one.
If you customized the user under which the service is started, do not forget to customize it in the newly installed service.
Upgrading from TeamCity version 2.x
If the service wrapper needs an update, the new version is downloaded into the / launcher.latest folder, however the changes are not applied automatically.
To upgrade the service wrapper manually, do the following:
1. Ensure the /launcher.latest folder exists. 2. Stop the service using \bin\service.stop.bat. 3. Uninstall the service using service.uninstall.bat. 4. Backup /launcher/conf/wrapper.conf file. 5. Delete /launcher. 6. Rename /launcher.latest to /launcher. 7. Edit /launcher/conf/wrapper.conf file. Check that the 'wrapper.java.command' property points to the java.exe file. Leave it blank to use registry to lookup for java. Leave 'java.exe' to lookup java.exe in PATH. For a standalone agent the service value should be ../jre/bin/java, for and agent installation on the server the value should be ../../jre/bin/java. The backup version of wrapper.conf file may be used. 8. Install the service using \bin\service.install.bat. 9. Make sure the service is running under the proper user account. Please note that using SYSTEM can result in failing builds which use MSBuild/Sln2005 configurations. 10. Start the service using \bin\service.start.bat. Warning This procedure is applicable ONLY for an agent running with new service wrapper. Make sure you are not running the agentd service.
Automatic Build Agent Upgrading
Starting with TeamCity 3.0, the core components and plugins for build agents are updated automatically. When the TeamCity server is upgraded, agents will automatically update themselves. The Agent (agent.bat, agent.sh, or agent service) will download the latest agent upgrade from the TeamCity server. When the download is complete and the agent is idle, it will start the upgrade process (the agent is stopped, the agent files are updated, and agent is restarted). This process may take about five minutes. It is important not to interrupt the upgrade process, doing so may cause the upgrade to fail and the agent will need to be manually reinstalled.
Do not close the console or restart the agent process during the upgrade! Notes on upgrading versions prior to 3.0.1: After agent.bat is launched, a command prompt console opens and then disappears while the agent files are updated. The console will reappear after the upgrade is complete and the agent restarts. Be patient, it can take around five minutes. Restarting the agent during this time may cause the upgrade to fail and the agent will need to be manually reinstalled. Since 3.0.1: The various console windows will open and close during the agent upgrade. Closing certain console windows may cause the upgrade to fail, and the agent will need to be manually reinstalled.
Document generated by Confluence on Jun 16, 2008 13:43 Page 99 Upgrade Notes
This page last changed on Apr 01, 2008 by ivrina. Upgrade Notes
From 3.1 to 3.1.1
No noteworthy changes From 3.0.1 to 3.1
Guest User and Agent Details
Starting from version 3.1, the Guest user does not have access to the agent details page. This has been done to reduce exposing potentially sensitive information regarding the agents' environment. In the Enterprise Edition, the Guest user's roles can be edited to provide the needed level of permission.
StarTeam Support
Working Folders in Use
Since version 3.1 when checking out files from a StarTeam repository TeamCity builds directory structure on the base of the working folder names, not just folder names as it was in earlier versions. So if you are satisfied with the way TeamCity worked with StarTeam folders in version 3.0, ensure the working folders' names are equal to the corresponding folder names (which is so by default).
Also note, that although StarTeam allows using absolute paths as working folders, TeamCity supports relative paths only and doesn't detect absolute paths presence. So be careful and review your configuration.
StarTeam URL Parser Fixed
In version 3.0 a user must have followed a wrong URL scheme. It was like starteam://server:49201/ project/view/rootFolder/subfolder/... and didn't work when user tried to refer a non-default view. In version 3.1 the native StarTeam URL parser is utilized. This means you now don't have to specify the root folder in the URL, and the previous example should look like starteam://server:49201/project/view/ subfolder/... From 3.0 to 3.0.1
Linux Agent Upgrade
• Due to an issue with Agent upgrade under Linux, Agent auxiliary Launcher processes may have been left running after agent upgrades. Versions 3.0.1 and up fix the issue. To get rid of the stale running processes, after automatic agent upgrade, please stop the agent (via agent.sh kill command) and kill any running java jetbrains.buildServer.agent.Launcher processes and start the agent again. From 2.x to 3.0
Incompatible changes
Please note that TeamCity 3.0 introduces several changes incompatible with TeamCity 2.x:
• build.working.dir system property is renamed to teamcity.build.checkoutDir. If you use the property in you build scripts, please update the scripts. • runAll.bat script now accepts a required parameter: start to start server and agent, stop to stop server and agent.
Document generated by Confluence on Jun 16, 2008 13:43 Page 100 • Under Windows, agent.bat script now accepts a required parameter: start to start agent, stop to stop agent. Note that in this case agent will be stopped only after it becomes idle (no builds are run). To force immediate agent stopping, use agent.bat stop force command that is available under both Windows and Linux (agent.sh stop force). Under Linux you can also use agent.sh stop kill command to stop agents not responding to agent.sh stop force.
Build working directory
Since TeamCity 3.0 introduces ability to configure VCS roots on per-Build Configuration basis, rather then per-Project, the default directory in which build configuration sources are checked out on agent now has generated name. If you need to know the directory used by a build configuration, you can refer to /work/directory.map file which lists build configurations with the directory used by them. See also Build Checkout Directory
User Roles when upgrading from TeamCity 1.x/2.x/3.x Professional to 3.x Enterprise
When upgrading from TeamCity 1.x/2.x/3.x Professional to 3.x Enterprise for the first time TeamCity's accounts will be assigned the following roles by default:
• Administrators become System Administrators • Users become Project Developers for all of the projects • The Guest account is able to view all of the project • Default user roles are set to Project Developer for all of the projects
See also:
• Licensing Policy • Editions
Document generated by Confluence on Jun 16, 2008 13:43 Page 101 Installing Tools
This page last changed on Nov 26, 2007 by chamilton. Installing Tools
TeamCity has a number of add-ons that provide seamless integration with various IDEs and greatly extend their capabilities with features like personal builds and pre-tested commit.
• Eclipse Plugin • IntelliJ IDEA Plugin • Syndication Feed • Visual Studio Plugin • Windows Tray Notifier
Document generated by Confluence on Jun 16, 2008 13:43 Page 102 Eclipse Plugin
This page last changed on May 04, 2008 by ivrina. Installing the TeamCity Plugin for Eclipse
Make sure you have Subclipse plugin installed before installing TeamCity plugin. Otherwise, on installing Subclipse after TeamCity plugin, you may experience an "Unable to create view: org/tigris/ subversion/subclipse/core/IResourceStateChangeListener" error. If you get this error, restart Eclipse using a "-clean" command-line option to avoid the error. Prerequisites
• Subclipse 1.2.x plugin: The current version of the Eclipse plugin only supports Remote Run and Pre-tested Commit for the Subversion Version Control System. You need to have Subclipse 1.2.x installed in Eclipse (update site for Subclipse 1.2). Please refer to the Eclipse plugin installation procedure for Subclipse plugin at http://subclipse.tigris.org/install.html. • JDK 1.5: Eclipse must be run under JDK 1.5 for the TeamCity plugin to work.
To install the TeamCity plugin for Eclipse:
1. Navigate to the My Settings and Tools page in the TeamCity UI and locate the TeamCity Tools section. 2. Under Eclipse plugin header, copy the update site link URL. For example, in Internet Explorer you can right-click the link and choose Copy shortcut on the context menu. 3. In Eclipse, choose Help | Software Updates | Find and Install on the main menu. The Install Feature Updates dialog appears. 4. Select the Search for new features to install option and click next. 5. Click the New Remote Site button. 6. Enter a name (for example TeamCity Plugin), paste the URL copied above (http:///update/eclipse/) into the URL field of the new update site in Eclipse, and click OK. 7. Click Finish and follow the installation instructions.
For detailed instructions on how to work with the plugin, refer to the TeamCity section of Eclipse's help system.
See also:
• UI Reference: My Settings And Tools
Document generated by Confluence on Jun 16, 2008 13:43 Page 103 IntelliJ IDEA Plugin
This page last changed on Jan 22, 2008 by yaegor.
Installing the Plugin for IntelliJ IDEA
Installing the Plugin from the Plugin Repository
To install the TeamCity plugin for IntelliJ IDEA:
1. In IntelliJ IDEA, open the Settings dialog. Press (Ctrl+Alt+S) or choose (File | Settings...) from the main menu. 2. Click the Plugin button under IDE Settings to invoke the plugin dialog. 3. On the Plugin dialog, click the Available tab to view a list of available plugins. 4. Scroll down and highlight the JetBrains TeamCity Plugin, click the button, and click OK. 5. Restart IntelliJ IDEA.
Note Please note that the plugin repository plugin version corresponds to TeamCity 3.0 version. If you have later TeamCity server version, please navigate to TeamCity menu in the IntelliJ IDEA and invoke Update command to install the plugin version matching the server version. Manually Installing the Plugin
The plugin for IntelliJ IDEA can be downloaded from the TeamCity Tool area on the My Settings & Tools page.
To install the TeamCity plugin for IntelliJ IDEA:
1. Navigate to the My Settings & Tools page. Under the IntelliJ IDEA Plugin section in the TeamCity Tools area, click the download link, and save the archive. 2. Make sure that IntelliJ IDEA is not running and unzip the archive into the IntelliJ IDEA user plugins directory at: • Windows: C:\Documents and Settings\\.IntelliJIdea70\config\plugins • OS X: $HOME/Library/Application Support/IntelliJIDEA70 • Linux/Unix: $HOME/.IntelliJIdea70/config/plugins
Note After you have installed a newer version of the plugin, you cannot rollback to its previous version. Additional information on how to work with TeamCity plugin is available in IntelliJ IDEA Help System (shipped with IntelliJ IDEA).
Document generated by Confluence on Jun 16, 2008 13:43 Page 104 Syndication Feed
This page last changed on Nov 29, 2007 by chamilton. Syndication Feed
To configure a syndication feed for obtaining information about the builds of certain build configurations:
1. In the TeamCity Tools section, click the Customize link. 2. In the Feed URL Generator page specify the build configurations and events (builds and/or changes) you want to be notified about, and define authentication settings. 3. Copy the Feed URL, generated by TeamCity, to your feed reader, or click Subscribe. 4. Preview summary of subscription and click Subscribe now.
Document generated by Confluence on Jun 16, 2008 13:43 Page 105 Visual Studio Plugin
This page last changed on Jan 21, 2008 by chamilton. Visual Studio Plugin
The TeamCity plugin for Microsoft Visual Studio 2005/2008 provides the following features:
• remote run (TFS and Subversion only) • pre-tested commit (TFS and Subversion only) • navigation to build results • viewing failed NUnit/TFS unit test stack traces • viewing the results of the integration of your changes into the project code base
For detailed instructions on how to use the plugin, refer to the TeamCity Help section, embedded in Microsoft Visual Studio's Help System.
Note
In order to enable navigation to the failed NUnit/TFS unit tests in Visual Studio by clicking the links in the Web UI, make sure that .pdb file generation for the assemblies involved in NUnit/TFS unit tests is switched on. Installing the Plugin
Download and install the plugin available in the TeamCity Tools section of the My Settings and Tools page and follow the installation wizard.
Requirements
• The TeamCity plugin for Microsoft Visual Studio requires Microsoft Visual Studio 2005/2008. • To use the remote run and pre-tested commit features with TFS, Team Explorer must be installed. Refer to MSDN documentation for information on installing Team Explorer. • To use these features with Subversion, use the Subversion command-line client version 1.4.0 or later.
Document generated by Confluence on Jun 16, 2008 13:43 Page 106 Windows Tray Notifier
This page last changed on Dec 04, 2007 by mio.
Windows Tray Notifier
The Windows Tray Notifier is a utility that helps you to stay up-to-date with your team's software building process. With the Windows Tray Notifier you:
• are always logged in to TeamCity, • receive notifications only about specific events, • monitor desired projects in the Windows Tray. Installing the Windows Tray Notifier
To install the Windows Tray Notifier:
1. Navigate to the My Settings & Tools page, and, in the TeamCity Tools area, click the download link under Windows tray notifier. 2. Wait until the plugin downloads completely. 3. Run the TrayNotifierInstaller.msi file. Working with the Windows Tray Notifier
After installing the Windows Tray Notifier, you can continue working in the IDE but effortlessly stay-up-to date with the most recent changes in the project code base using the notifier's various elements:
• The Notifier Icon • The TeamCity Quick View Window • Windows Tray Popup Alerts • Right-Click Functionality Tip You can customize your watched projects and build configurations to help avoid information overload and change the information available in the quick view window: ° - Right-click the Notifier Icon and select Configure Watched Builds. You will be directed to TeamCity's Windows tray notifier settings page where you can: - Select the desired build configurations and events on which you want to be notified.
The Notifier Icon
The Notifier icon appears in Windows System Tray as soon as you launch the Windows Tray Notifier. It shows the status of projects which you (or your TeamCity Administrator) have selected to monitor. The status icon changes to reflect the state of watched projects and build configurations. Here is a list of possible states of the build configurations.
Icon Meaning Build is successful Build failed and nobody has taken responsibility Some team member has taken responsibility for the build failure The person responsible for the build failure has submitted a fix, but the build has not executed successfully yet Build configuration is paused, and builds are not triggered automatically The Notifier icon always shows the status of the last completed build of the your watched project or build configurations, unless you selected Notify when the first error occurs on the Windows
Document generated by Confluence on Jun 16, 2008 13:43 Page 107 Tray Notifier settings page. In this case, the Notifier icon does not wait for the failing build to finish, it displays a failed icon as soon as the running build fails a test.
The TeamCity Quick View Window
A click on the status icon opens the TeamCity Quick View window.
Click the results or changes links to navigate to the Build Results and Changes pages in TeamCity's web interface, respectively.
Windows Tray Popup Alerts
Windows tray popup alerts display brief build results information for the specified build configurations and notification events.
Click the link on the popup to go the build results page for more details.
Right-Click Functionality
Right-clicking the icon gives you quick access to all of the Windows Tray Notifier's functions.
Option Description Open Quick View Window Displays the Quick View Window
Document generated by Confluence on Jun 16, 2008 13:43 Page 108 Go to Projects page... Opens the Projects tab. Go to My Changes page... Opens the My Changes tab Configure Watched Builds... Opens the Windows Tray Notifier settings page. Tip: Avoid information overload and customize the quick view window by editing your settings on this page. Auto Upgrade Select this option to allow the program to automatically upgrade itself. Run on Startup Select this option to automatically launch the program when windows boots. About Displays the information on the program's splash screen. Logout Use this function to log out of the TeamCity server. This will allow you to a different one. Exit Quits the program
Document generated by Confluence on Jun 16, 2008 13:43 Page 109 System Administrator Reference
This page last changed on Nov 08, 2007 by mio. System Administrator Reference
• Configuring the Server • Enabling the Status Widget for Build Configurations • Enterprise License Expiration • Logs of Internal Events • Managing Projects • Notifier Templates Configuration • Patterns For Accessing Build Artifacts • System Properties for Running the Server • System Properties of a Build Configuration • Third-Party License Agreements • Troubleshooting
Document generated by Confluence on Jun 16, 2008 13:43 Page 110 Configuring the Server
This page last changed on Apr 24, 2008 by ivrina. Configuring the Server
Server configuration is only available to the System Administrators.
To edit server configuration:
1. In the Administration page, click the link Edit Server Configuration. 2. In the Edit Server Configuration page, you can: • View and ; • Specify the server URL; • View the current authentication scheme, configure the welcome message and enable or disable anonymous login. Authentication scheme can be configured manually, as described in the section Authentication Settings • Configure email and Jabber notification settings.
Also in this part:
• Accessing Server from Scripts • Authentication Settings • Build Script Interaction with TeamCity • Changing user password with default authentication scheme • Configuring Server URL • Configuring UTF8 Character Set for MySQL • Enabling Guest Login • Including Third-Party Reports in the Build Results • Mapping External Links in Comments • Using HTTPS to access TeamCity server
Document generated by Confluence on Jun 16, 2008 13:43 Page 111 Accessing Server from Scripts
This page last changed on Dec 06, 2007 by yaegor. Accessing Server from Scripts
The TeamCity server supports basic HTTP authentication allowing to access certain web server pages and perform actions from various scripts.
Use valid TeamCity server username and password to authenticate using basic HTTP authentication.
You may want to configure the server to use HTTPS as username and password are passed in clear text during basic HTTP authentication.
To use a basic HTML authentication instead of redirecting to the login page, prepend a path in usual TeamCity URL with "/httpAuth". For example: http://buildserver:8111/httpAuth/action.html?add2Queue=bt7
The HTTP authentication can be useful when downloading build artifacts and triggering a build.
If you have Guest user enabled, it can be used to perform the action too. Use "/guestAuth" before thr URL path to perform the action on Guest user behalf. For example: http://buildserver:8111/guestAuth/action.html?add2Queue=bt7
In TeamCity Enterprise version, please make sure the user used to perform the authentication (or Guest user) has appropriate role to perform the necessary operation.
Triggering a Build From Script
To trigger a build, send the HTTP GET request for the URL: http:///httpAuth/ action.html?add2Queue= performing basic HTTP authentication.
Some tools (for example, Wget) support the following syntax for the basic HTTP authentication: http://:@/httpAuth/action.html?add2Queue=
Since TeamCity 3.0, you can trigger a build on a specific agent passing additional agentId parameter with the agent's Id. You can get the agent Id from the URL of the Agent's details page. For example, you can infer that agent's Id equals "2" if it's details page has the following URL: http://teamcity.jetbrains.com/agentDetails.html?id=2
To trigger a build on two agents at the same time, use the following URL: http://testuser:[email protected]/httpAuth/action.html? add2Queue=bt10&agentId=1&agentId=2
Document generated by Confluence on Jun 16, 2008 13:43 Page 112 Authentication Settings
This page last changed on May 07, 2008 by ivrina. Authentication Settings
Out-of-the-box TeamCity Enterprise edition supports three authentication schemes:
• Default Authentication (cross-platform) • Windows Domain Authentication (Windows platforms only) ° Windows Domain Authentication on Unix-like computers ( Only available in TeamCity 3.1) • LDAP Authentication (cross-platform)
TeamCity Professional edition only supports TeamCity Default Authentication. Active authentication scheme is configured in the auth-type section of the main-config.xml file located in the /config directory, for example:
Welcome to TeamCity, your team building environment!
Authentication type is defined by the login module, welcome message and the possibility to use anonymous login. Built-in login modules are:
• jetbrains.buildServer.serverSide.impl.auth.DefaultLoginModule for Default Authentication • jetbrains.buildServer.serverSide.impl.auth.NTDomainLoginModule for Windows Domain Authentication • jetbrains.buildServer.serverSide.impl.auth.LDAPLoginModule for LDAP Authentication TeamCity extensibility note: Any implementation of javax.security.auth.spi.LoginModule can be used, provided it is registered via jetbrains.buildServer.serverSide.auth.LoginModuleDescriptor bean.
Default Authentication
Configuration of TeamCity Data Directory/config/main-config.xml:
Welcome to TeamCity, your team building environment!
Users database is maintained by TeamCity. New users are added by TeamCity administrator (in administration area section) or user are self-registered if tag is specified.
Document generated by Confluence on Jun 16, 2008 13:43 Page 113 Windows Domain Authentication
Configuration of TeamCity Data Directory/config/main-config.xml:
Welcome to TeamCity, your team building environment!
Prior to TeamCity 3.1, Windows Domain Authentication was supported only if TeamCity server was installed under Windows 2000, Windows XP or Windows Server 2003. See below for the features introduced in 3.1.
Prior to TeamCity 3.1, all Windows domain users that can log on to the machine running TeamCity server can also log in into TeamCity using the same credentials.
To log in to TeamCity users should provide their user name in the form DOMAIN\user.name and their domain password. TeamCity 3.1 also supports logging in using @ syntax. It is also possible to log in using only a username if the domain is added to the TeamCity Data Directory/ config/ntlm-config.properties file.
Windows Domain Authentication on Unix-like Computers (TeamCity 3.1 Only)
Support for Windows Domain Authentication on Unix-like computers is available in TeamCity 3.1. For this to work, check the /config/ntlm-config.properties file and make sure the following line is commented out.
# ntlm.compatibilityMode=true
Please refer to the http://jcifs.samba.org/src/docs/api/ page for information about other supported properties.
If you want to use the NT domain authentication available in TeamCity version prior to 3.1, ensure the line ntlm.compatibilityMod=true is present and not commented in the ntlm-config.properties file.
LDAP Authentication
Configuration of /config/main-config.xml:
Welcome to TeamCity, your team building environment!
Authentication is performed by direct login into LDAP with credentials entered into the login form.
Environment for initial context is initialized with java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory and then all properties from /config/ldap-config.properties file are loaded. Refer to the http:// java.sun.com/products/jndi/tutorial/ldap/security/ldap.html page for more information about property names and values.
Use the LDAP explorer to browse LDAP directory and verify the settings (i.e.http://www.jxplorer.org/).
Document generated by Confluence on Jun 16, 2008 13:43 Page 114 You can also specify multiple servers using the following pattern: java.naming.provider.url="ldap://ldap.mycompany.com:389 ldap://ldap2.mycompany.com:389 ldap:// ldap3.mycompany.com:389"
Active Directory
The following template enables authentication against active directory:
Add the following code to the /config/ldap-config.properties file. java.naming.referral=follow java.naming.provider.url=ldap://main.labs.intellij.net:389/CN=users,DC=Labs,DC=IntelliJ,DC=Net java.naming.security.authentication=simple
Non-AD LDAP server issues
By default login format is restricted to DOMAIN\sAMAccountName (i.e. "LABS\alexey.gopachenko"). But since version 2.1 you can override this restriction by adding property loginFilter, value is java.util.RegEx expression to match against. (I.e. loginFilter=.+ will accept any non-empty login).
OpenLDAP users can benefit from formatDN property. If formatDN is defined then it is used as user DN with $login$ substring replaced with anyting what user enters into login field, i.e formatDN=uid=$login$,ou=people,dc=company,dc=com
See also:
• UI Reference: Administration
Document generated by Confluence on Jun 16, 2008 13:43 Page 115 Build Script Interaction with TeamCity
This page last changed on May 30, 2008 by yaegor. Build Script Interaction with TeamCity
If TeamCity doesn't support your testing framework or build runner out of the box, it is still possible to reap the many of benefits that TeamCity provides by customizing your build scripts to interact with the TeamCity server. This makes a wide range of features available to any team regardless of their testing frameworks and runners. Some of these features include displaying real-time test results and customized statistics, changing the build's status, and publishing artifacts before the build is finished.
In this section:
• Service Messages ° Reporting tests ° Publishing artifacts while the build is still in progress ° Reporting build progress ° Reporting build status ° Reporting build number ° Reporting build statistics • teamcity-info.xml ° Modifying the build status ° Reporting and displaying custom statistics
Service Messages
Service messages are used to pass commands/build information to TeamCity server from the build script. In order to be processed by TeamCity they should be printed into standard output stream of the build (otherwise, if the output is not in the service message syntax, it should appear in the build log).
Service messages support two formats:
• Message and single parameter:
##teamcity[message 'value']
• Message and multiple parameters:
##teamcity[message name1='value1' name2='value2']
Multiple parameters message can more formally be described as:
• messageName is a name of the message. See below for supported messages. The message name should be a valid Java id (only alpha-numeric characters and "-", starting with a alpha character) • propertyName is a name of the message attribute. Should be a valid Java id. • value is a value of the attribute preceding it. Should be an escaped value (see below). • WSP is a required whitespace(s): space or tab character (\t) • OWSP is an optional whitespace(s) • NEWLINE is a newline character(s): \n or \r • ... is any number of WSPpropertyNameOWSP=OWSP'_value'_ blocks
Document generated by Confluence on Jun 16, 2008 13:43 Page 116 For escaped values, TeamCity uses a vertical bar "|" as an escape character. In order to have certain characters properly interpreted by the TeamCity server they must be preceded by a vertical bar. For example, the following message:
##teamcity[testStarted name='foo|'s test'] will be displayed in TeamCity as 'foo's test'. Please see the table below.
Character Should be escaped as ' (apostrophe) |' \n (line feed) |n \r (carriage return) |r | (vertical bar) || ] (closing bracket) |] Each message should be followed by a newline.
Reporting Tests
As TeamCity reports tests results on-the-fly, every testing framework needs its own support for this feature to work. If TeamCity doesn't support your testing framework or build runner, it is possible to modify your build script to send this information to the TeamCity server using service messages that are sent via the standard output of the build process. This makes it possible to display test results in real- time, make test information available on the Tests tab of the Build Results page, and publish artifacts while the build is still in progress.
Here is the list of supported test service messages:
Indicates that the test "testname" was run. If testFailed message is not present, the test is regarded as successful. All the other test messages (except testIgnored) with the same name attribute should appear between the testStarted and testFinished (in that order).
Test output reporting (to be shown as the test result if the test fails). A test should have no more then one testStdOut and one testStdErr message. The messages should appear inside testStarted and testFinished messages with the matching name attribute.
Document generated by Confluence on Jun 16, 2008 13:43 Page 117 ##teamcity[testFailed type='comparisonFailure' name='testname' message='failure message' details='stack trace' expected='expected value' actual='actual value']
Indicates that the test with the name name has failed. Only one testFailed messages should appear for a given test name. actual and expected attributes can be used for reporting comparison failure. The values will be used when opening the test in the IDE. The messages should appear inside testStarted and testFinished messages with the matching name attribute.
Publishing Artifacts while the Build is Still in Progress
Another cool feature of service messages is that now you can publish build artifacts, while the build is still running. Just output the following line:
##teamcity[publishArtifacts '']
And the files matching the will be uploaded and visible as artifacts of the running build.
Publishing artifacts process can affect the build because it consumes network traffic and some disk/ CPU resources (should be pretty negligible for not large files/directories).
Artifacts that are specified in the build configuration setting will be published as usual.
Reporting build progress
You can use special progress messages to mark long-running parts in a build script. These messages will be shown on the projects dashboard for corresponding build and on the build results page.
To log single progress message use:
##teamcity[progressMessage '']
This progress message will be shown until another progress message occurs or until next target starts (in case of Ant builds).
If you wish to show progress message for a part of a build only you can use:
The same message should be used for both progressStart and progressFinish. This allows nesting of progress blocks. Also note that in case of Ant builds progress messages will be replaced if Ant target starts.
In previous TeamCity versions (< 3.1) we used other format for the progress messages. If for some reason you cannot modify your build scripts to support new format you can install this plugin: deprecated-progress.jar. This jar file should be copied to the TeamCity WEB-INF/lib directory and TeamCity server must be restarted after that.
Reporting Build Status
TeamCity allows user to change the build status directly from the build script. To set the status and change the text of the build status (e.g. note the number of failed tests if the test framework is not supported by TeamCity), use the buildStatus message with the following format:
Document generated by Confluence on Jun 16, 2008 13:43 Page 118 ##teamcity[buildStatus status='' text='{build.status.text} and some aftertext'] where:
• The status attribute may take following values: FAILURE, SUCCESS, NORMAL, ERROR. • {build.status.text} is an optional substitution pattern which represents the status, calculated by TeamCity automatically using passed test count, compilation messages and so on. The status, which is set using such attribute, will be presented while build is running and will affect final build results.
Reporting Build Number
To set a custom build number directly, specify a buildNumber message using the following format:
##teamcity[buildNumber '']
In the value, you can use the {build.number} attribute to show the current build number provided by TeamCity. For example:
In TeamCity, it is possible to provide custom graphs. But before describing a custom graph you need to report related build statistics. You can publish the build statics values in two ways:
• Using a service message in a build script directly • Providing data using the teamcity-info.xml file
To report build statistics using service messages:
• Specify a 'buildStatisticValue' service message with the following format for each statistics value you want to report:
##teamcity[buildStatisticValue key='' value='']
TeamCity-info.xml
It is also possible to have the build script collect information, generate an XML file called teamcity- info.xml in the root build directory. When the build finishes, this file will automatically be uploaded as a build artifact and processed by the TeamCity server.
Modifying the Build Status
TeamCity has the ability to change the build status directly from the build script. You can set the status (build failure or success) and change the text of the build status (e.g. note the number of failed tests if the test framework is not supported by TeamCity).
XML schema for teamcity-info.xml
It is possible to set the following information for the build:
• Build number — Sets the new number for the finished build. You can reference the TeamCity- provided build number using {build.number}. • Build status — Change the build status. Supported values are "FAILURE" and "SUCCESS".
Document generated by Confluence on Jun 16, 2008 13:43 Page 119 • Status text — Modify the text of build status. You can replace the TeamCity-provided status text or add a custom part before or after the standard text. Supported action values are "append", "prepend" and "replace".
Example teamcity-info.xml file:
fitnesse: 45 coverage: 54%
It is up to you to figure out how to retrieve test results that are not supported by TeamCity and accurately add them to the teamcity-info.xml file.
Reporting and Displaying Custom Statistics
It is possible to provide custom graphs in TeamCity. Custom graphs are shown at the end of Statistics tab of build configuration page. There is no need to develop any additional TeamCity plugins, just provide the data in the TeamCity-info.xml file and organize the graph.
To create a custom graph:
1. [Have the build script provide the statistics data using service messages in the build script or the teamcity-info.xml file. 2. Describe your graphs using main-config.xml file.
Providing data using the teamcity-info.xml file
This file should be created by the build in the root directory of the build. You can publish multiple statistics (see the details on the data format below) and create separate graphs for each set of values.
The teamcity-info.xml file should contain code in the following format (you can combine various data in the teamcity-info.xml file):
Describing graphs using the main-config.xml file
Add the following lines of code within the tag of the /config/ main-config.xml file:
Document generated by Confluence on Jun 16, 2008 13:43 Page 120 Changing user password with default authentication scheme
This page last changed on May 12, 2008 by pavel.sher. Changing user password with default authentication scheme and database
The following procedure is suitable for default authentication scheme and default database (HSQLDB) only.
To change user password:
1. Switch to the /webapps/ROOT/WEB-INF/lib directory 2. Invoke the following command:
java -cp server.jar;hsqldb.jar ChangePassword
You can skip the option, if you are using default path for TeamCity data files: /.BuildServer
Document generated by Confluence on Jun 16, 2008 13:43 Page 121 Configuring Server URL
This page last changed on Apr 09, 2008 by ivrina. Configuring Server URL
Starting from TeamCity 3.0 server URL can be modified right from the Administration -> Server configuration page.
In most cases TeamCity correctly autodetects its own URL and uses it for constructing URLs in notification messages. But sometimes it is impossible, for example, the server might be running on HTTP and HTTPS or it might be hidden behind the Apache web server. For such cases you can specify server URL in the main-config.xml file (no server restart is required after the change):
This URL will be used when URLs in notification messages are constructed.
Document generated by Confluence on Jun 16, 2008 13:43 Page 122 Configuring UTF8 Character Set for MySQL
This page last changed on Apr 29, 2008 by ivrina. Configuring UTF8 Character Set for MySQL
To create a MySQL database which uses the utf8 character set:
1. Create a new database:
CREATE DATABASE DEFAULT CHARACTER SET utf8
2. Open /config/database.properties, and add the characterEncoding property:
connectionProperties.characterEncoding=UTF-8
To change the character set of an existing MySQL database to utf8:
1. Shut the TeamCity server down. 2. Dump the database data to the file dump_data.sql:
mysqldump -t -u -p >dump_data.sql;
3. Dump the database schema to the file dump_schema.sql:
4. Edit dump_schema.sql. Remove DEFAULT CHARSET= from the table and column definitions. 5. Create a new database with uft8 as the default character set:
CREATE DATABASE DEFAULT CHARACTER SET utf8; 6. Import dump_schema.sql into the new database:
mysql -u -p
mysql -u -p/config/database.properties file as follows: • change connectionUrl property to:
jdbc:mysql:/// • add characterEncoding property:
connectionProperties.characterEncoding=UTF-8
Document generated by Confluence on Jun 16, 2008 13:43 Page 123 Enabling Guest Login
This page last changed on Nov 07, 2007 by mio. Enabling Guest Login to TeamCity
To enable guest login to TeamCity:
1. Navigate to Administration page and click Edit server settings link. 2. Select Allow to login as a guest user option. The Login as a guest user link appears on the Login page. Notes • Alternatively, you can edit the auth-type section of the main-config.xml file and set . • The number of quests which can log in to TeamCity is unlimited. • Guest login doesn't require any licenses.
See also:
• Authentication Settings • Licenses
Document generated by Confluence on Jun 16, 2008 13:43 Page 124 Including Third-Party Reports in the Build Results
This page last changed on May 07, 2008 by ivrina. Including Third-Party Reports in the Build Results
TeamCity can be extended to include information provided by third-party reporting tools.
If your reporting tool produces a report in HTML format, you can add a new tab to the build results page which will show the report. To do this specify the report as an artifact and modify the configuration to instruct the server to display the report whenever it is found in the artifact.
To enable including a report in a separate tab:
1. For the build configuration, that produces a report, add an archive or directory to the Artifact paths of the build runner. 2. Add the following line within the tag of the /config/main- config.xml file:
where:
• title is a unique title of the report tab • basePath is an archive or directory that contains the generated report, something like javadoc or report.zip • startPage is a relative path of the start page within the report archive or directory.
See also:
• Build Script Interaction with TeamCity
Document generated by Confluence on Jun 16, 2008 13:43 Page 125 Mapping External Links in Comments
This page last changed on Nov 07, 2007 by mio. Mapping External Links in Comments
TeamCity allows to map the issues in comments of the users' commits in the version control system using the search and replace pattern.
To configure mapping:
1. Navigate to the file TeamCity data directory/config/main-config.xml 2. Locate section , or create one under the tag, if it doesn't exist (you may refer to the main-config.dtd file for the XML structure definition) 3. Specify the search and replace patterns. For example, you can use the following pattern for enabling JIRA integration:
... ...
NOTE Search & replace patterns have java.util.regex.Pattern syntax.
Document generated by Confluence on Jun 16, 2008 13:43 Page 126 Using HTTPS to access TeamCity server
This page last changed on Nov 08, 2007 by chamilton. Using HTTPS to access TeamCity server
This document describes how to configure various TeamCity server clients to use HTTPS for communicating with the server. We assume that you have already configured HTTPS in your web server. See how to do this for Tomcat here: http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html.
If your certificate is valid (i.e. it was signed by a well known Certificate Authority like Verisign), then TeamCity clients should work with HTTPS without any additional configuration. All you have to do is to use https:// links to the TeamCity server instead of http://.
If your certificate is not valid:
• To enable HTTPS connections from TeamCity Visual Studio plugin and Tray notifier, point your Internet Explorer to the TeamCity server using https:// URL and import the server certificate into the browser. After that Visual Studio plugin and Tray notifier should be able to connect by HTTPS. • To enable HTTPS connections from Java clients, save server certificate to a file, and then import it into the corresponding Java keystore using keytool program. By default, Java keystore is protected by password: changeit • For Build Agent import certificate, use the following command:
Document generated by Confluence on Jun 16, 2008 13:43 Page 127 Enabling the Status Widget for Build Configurations
This page last changed on Mar 28, 2008 by ivrina.
Enabling the Status Widget for Build Configurations
By enabling the status widget, it is possible for any external web page to retrieve the latest build status of one or more build configurations.
In addition to enabling this option when creating or editing the general settings of the build configuration, you need to include the following snippets of code in the web page source:
• Add this code sample in the
section (or alternatively, add the withCss=true parameter to externalStatus.html):
• Insert this code sample where you want to display the build configuration's status:
• If you prefer to use plain HTML instead of javascript, omit the js=1 parameter • If you want to include default CSS styles without modifying the
section, add the withCss=true parameter • To provide up-to-date status information on specific build configurations, use the following parameter in the URL as many times as needed:
&buildTypeId=
• It is also possible to show the status of all a project's build configurations by replacing "&buildTypeId=" with "&projectId=". You can select a combination of these parameters to display the needed projects and build configurations on your web page. • You can also download and customize the externalStatus.css file (e.g. you can disable some columns by using display: none; See comments in externalStatus.css). But in this case, you must not include the withCss=true parameter, but provide the CSS styles explicitly, preferably in the section, instead.
See also:
• UI Reference: Feed URL Generator
Document generated by Confluence on Jun 16, 2008 13:43 Page 128 Enterprise License Expiration
This page last changed on Dec 03, 2007 by yaegor. Enterprise License Expiration
When an Enterprise license expires (or the license key becomes corrupted), TeamCity reverts to working in Professional mode.
This means that certain features will be disabled or have limited functionality and that builds will not run unless a number of stipulations are met. (For details on TeamCity Professional's limitations please see Editions).
TeamCity preserves your Enterprise settings when downgrading to Professional. However, if you have to remove users or build configurations to work in Professional mode, it is recommended you make a backup of the TeamCity Data Directory to use when restoring Enterprise mode. Feature changes when reverting from Enterprise to Professional
Roles
• System and Project Administrators in Enterprise change into Administrators. (TeamCity actually checks to see if the EDIT_PROJECT permission is present in the user's account). • Project Developers and Agent Managers revert to Users. • Guest users, regardless of how they were configured in Enterprise mode, will only be able to view projects.
(See: Roles)
User Authentication
NT and LDAP Authentication will not work in Professional mode. If you were not already using TeamCity's default authentication scheme then up to 20 TeamCity users will need to have new accounts created for them using this scheme.
After you enter a valid Enterprise license all limitations will be removed and:
• Enterprise user roles and permissions are preserved while running in Professional mode and are automatically restored • Users created while working in Professional mode will be assigned the "Default User" settings when switching to Enterprise.
If you made a backup of your TeamCity Data Directory because you had more than 20 build configurations or users, and you ran builds in Professional mode, you will want to back up your current TeamCity Data Directory to preserve your most up-to-date build information. Restore the original "Enterprise" backup before entering your Enterprise license, then manually copy the specific build folders from the more recent "Professional" backup.
Document generated by Confluence on Jun 16, 2008 13:43 Page 129 Logs of Internal Events
This page last changed on May 26, 2008 by yaegor. Logging the Internal Events
TeamCity uses Log4J for internal logging of events. The following logging rules are used: Build agent logs
Build agent Log4J configuration file is /conf/teamcity-agent-log4j.xml Build agent logs are placed to /logs directory. General build agent log is named teamcity-agent.log When build agent is installed using Java Service Wrapper (as windows service), it logs its output and error output to /logs/wrapper.log .
To configure location of the logs, you have to alter value of teamcity_logs property (passed to JVM via - D option). To change Log4J configuration file location, you have to change value of log4j.configuration property.
Such changes should be made in:
• /launcher/conf/wrapper.conf file if build agent is installed as service • /bin/agent.(sh|bat) if the agent is run from the command line TeamCity server logs
TeamCity server Log4J configuration file is /conf/teamcity-server-log4j.xml TeamCity server logs are placed to /logs directory and prefixed with teamcity- prefix. General TeamCity server log is named teamcity-server.log, there are also teamcity-activities.log and teamcity-vcs.log.
To configure location of the logs, you have to alter value of teamcity_logs property (passed to JVM via - D option). To change Log4J configuration file location, you have to change value of log4j.configuration property.
Such changes should be made:
• in files /bin/runAll.(bat|sh) if server is run from the command line (or in catalina.(bat|sh) • Using tomcat6w.exe, if TeamCity is installed as Windows service • If you used the WAR-distribution to install TeamCity, by default you should be able to find teamcity.log file in the /logs directory. You may add log4j.configuration property to specify Log4J configuration for TeamCity.
Document generated by Confluence on Jun 16, 2008 13:43 Page 130 Managing Projects
This page last changed on Nov 23, 2007 by mio. Managing Projects
To create a new project:
1. On the Administration page, click the Create project link. 2. On the Create New Project page, specify the project name and optional description. 3. Click Create. An empty project is created. Tip To configure an existing project, select the desired project in the list, and click Edit. 4. Create build configurations (select build settings, configure VCS settings, and choose build runners) for the project. 5. Assigning Build Configurations to Specific Build Agents
Document generated by Confluence on Jun 16, 2008 13:43 Page 131 Assigning Build Configurations to Specific Build Agents
This page last changed on Feb 11, 2008 by chamilton. Assigning Build Configurations to Specific Build Agents
It is sometimes necessary to manage the Build Agents' workload more effectively. For example, if the time-consuming performance tests are run, the Build Agents with low hardware resources may slow down. As a result, more builds will enter the build queue, and the feedback loop can become longer than desired. To avoid such situation, you can:
1. Establish a run configuration policy for an agent, which defines the build configurations to run on this agent. 2. Define special agent requirements, to restrict the pool of agents, on which a build configuration can run the builds. These requirements are:
• Build Agent name. If the name of a build agent is made a requirement, the build configuration will run builds on this agent only. • Build Agent property. If a certain property, for example, a capability to run builds of a certain configuration, an operating system etc., is made a requirement, the build configuration will run builds on the agents that meet this requirement. Tip You can modify these parameters when setting up the project or build configuration, or any moment you need. The changes you make to the build configurations are applied on the fly.
Establishing a Run Configuration Policy
To establish a Build Agent's run configuration policy:
1. Click the Agents tab and select the desired build agent. 2. Click the Compatible Configurations tab. 3. Select Run selected configurations only and tick the desired build configurations names to run on the build agent.
Making Build Agent Name and Property a Build Configuration Requirement
To make a build configuration run the builds on a build agent with the specified name and properties:
1. Click the Administration tab and select the desired build configuration. 2. Click Agent Requirements (see Agent Requirements). 3. Click the Add requirement for a property link, type the agent.name property, set its condition to equals and specify the build agent's name. Note You can also use the condition contains, however, it may include more than one specific build agent (e.g. a build configuration with a requirement agent.name contains Agent10, will run on agents named Agent10, Agent10a, and Agent10b). 4. Click the Add requirement for a property link and add the required property, condition, and value. For example, if you have several Linux-only builds, you can add the os.name property and set the starts with condition and the linux value. Tip On the Agent Requirements page, click the Frequently used requirements link to quickly add the regularly used requirements.
Document generated by Confluence on Jun 16, 2008 13:43 Page 132 See also:
Document generated by Confluence on Jun 16, 2008 13:43 Page 133 Configuring Artifact Dependencies
This page last changed on Mar 14, 2008 by pavel.sher. Configuring Artifact Dependencies
A build configuration can be made dependent on the artifacts of builds of some other build configurations. That means that before the build, all artifacts, the build configuration is dependent on will be downloaded and placed in their configured target locations and then can be used by the build.
There are two ways to define artifact dependencies:
• Via web UI • Via Ant build.xml with using Ivy tasks or Ivy tool from the command line
Configuring Dependencies Using the Web UI
To add dependencies to a build configuration:
1. Open Edit build configuration page. 2. In the Build Configuration Steps, choose Artifact dependencies. 3. Click Add new dependency link. 4. In the Artifacts Dependencies page, specify the following settings: • Build configuration and build from which artifacts should be taken • Paths to artifacts as they are shown on server • Destination path on agent where to put downloaded artifacts.
Configuring Dependencies in Ant build.xml
This solution is more complicated but allows greater flexibility. For example, configuring dependencies in this way will allow you to start a personal build and verify that your build is still compatible with dependencies.
To configure dependencies in Ant build.xml:
1. Download Ivy.
TeamCity itself acts as an Ivy repository. You can read more about the Ivy dependency manager here: http://ant.apache.org/ivy/.
2. Add Ivy to the classpath of your build. 3. Create ivyconf.xml file that contains some meta information about TeamCity repository. This file should have the following content:
Document generated by Confluence on Jun 16, 2008 13:43 Page 134
4. Replace YOUR_TEAMCITY_HOST_NAME with the host name of your TeamCity server.
5. Place ivyconf.xml in the directory where your build.xml will be running.
6. In the same directory create ivy.xml file in which define which artifacts should be downloaded and where to put them, for example:
Where
• YOUR_ORGANIZATION should be replaced with the name of your organization. • YOUR_MODULE should be replaced with the name of your project or module where artifacts will be used. • BUILD_CONFIGURATION_ID should be replaced with id of the build configuration from where artifacts are downloaded. You can obtain this id from the links in your TeamCity server (you should take value of buildTypeId parameter). e.g. bt20 • BUILD_REVISION can be either build number or one of the following strings: ° latest.lastFinished ° latest.lastSuccessful ° latest.lastPinned • ARTIFACT_FILE_NAME_WITHOUT_EXTENSION file name or regular expression of the artifact without extension part. • ARTIFACT_FILE_NAME_EXTENSION extension part of the artifact file name.
7. Modify your build.xml file and add tasks for downloading artifacts, for example (applicable for Ant 1.6 and later):
Please note that among ivy commons-httpclient, commons-logging and commons-codec should be in classpath of Ivy tasks.
Since 2.1 artifacts repository is protected by basic authentication. For accessing artifacts you should provide credentials to the task. For example:
Document generated by Confluence on Jun 16, 2008 13:43 Page 135 where TEAMCITY_HOST is hostname or IP address of your TeamCity server (without port and servlet context). As USER_ID/PASSWORD you can use either username/password of a regular TeamCity user or system properties teamcity.auth.userId/teamcity.auth.password.
The properties teamcity.auth.userId/teamcity.auth.password store automatically generated build- unique values whose only intended use is artifacts downloading within the build script. The values are valid only during the time the build is running. Using the properties is preferable to using reall user credentials since it allows the server to track artifacts downloaded by your build. If the artifacts were downloaded by the build configuration artifact dependencies or using the supplied properties, the specific artifacts used by the build will be displayed on the build results page. In addition, the builds which were used to get the artifacts from will not be cleaned up by the clean-up process much like the pinned builds.
Document generated by Confluence on Jun 16, 2008 13:43 Page 137 .NET Testing Frameworks Support
This page last changed on May 05, 2008 by ivrina. .NET Testing Frameworks Support
In order to support the real-time reporting test results, TeamCity should either run the tests using its own test runner or be able to interact with the testing frameworks so it receives notifications on test events. Custom TeamCity-aware test runners are used to implement the bundled support for the testing frameworks.
• TeamCity 3.0 testing frameworks support • TeamCity 3.1 testing frameworks support TeamCity 3.0
TeamCity NUnit Test Launcher
TeamCity uses its own NUnit tests launcher that can be used from the any runner. The tests are run according to the passed parameters and if the process is run inside TeamCity build agent environment, the results are reported to the TeamCity agent.
The properties are available as both environment variables and system properties are available under any build process running on TeamCity, e.g. NAnt, MSBuild, Ant, SimpleRunner, etc. teamcity.dotnet.nunitlauncher1.1 - full launcher application name for .Net Framework 1.1, NUnit 2.2.8 teamcity.dotnet.nunitlauncher2.0 - full launcher application name for .Net Framework 2.0, NUnit 2.2.8 teamcity.dotnet.nunitlauncher2.0.vsts - full launcher application name for .Net Framework 2.0, VSTS tests
Starting from TeamCity 3.1.x these properties are considered obsolete.
Inside the build run by TeamCity the name of the NUnit launcher can be obtained through the system properties and environment variables.
The launcher can be used in the build script to run the tests. e.g. here is an example for NAnt script (as of TeamCity 3.0):
Document generated by Confluence on Jun 16, 2008 13:43 Page 138 NAnt Runner
TeamCity provides custom task implementation. TeamCity automatically replaces the original task with its own task, so if your build script uses the nunit2 task, it will automatically work without any modifications to the build script.
MSBuild Runner
TeamCity provides custom NUnitTeamCity task and NUnit task that is compatible with NUnit task from MSBuild Community tasks project. The MSBuild NUnit/NUnitTeamCity tasks are a convenient way to run the tests for MSBuild and Solution 2005 builds. Example usage is (part of the MSBuild build script):
• Make sure to replace "." with "_", when using properties in MSBuild scripts. (i.e. use teamcity_dotnet_nunitlauncher_msbuild_task instead of teamcity.dotnet.nunitlauncher.msbuild.task) • TeamCity also provides a Solution 2005 Runner for Microsoft Visual Studio 2005 solution files. It allows you to use MSBuild-style wildcards for the assemblies to run unit tests on. TeamCity 3.1
NAnt Runner
Since TeamCity 3.1, the following options are supported for TeamCity task implementation:
Property name description teamcity.dotnet.nant.nunit2.failonfailureatendRun all tests and fails if at least one test has failed. teamcity.dotnet.nant.nunit2.platform Sets desired runtime execution mode for .NET 2.0 on x64 machines. Supported values are x86, x64 and ANY(default). teamcity.dotnet.nant.nunit2.version Specifies which version of the NUnit runner to use. Supported versions are: NUnit-2.2.10 (default), NUnit-2.2.9-VSTS and NUnit-2.4.6.
TeamCity 3.1 also supports the NAnt 0.86 runner and the NUnit 2.4 testing framework.
TeamCity NUnit test launcher will run tests in the .NET Framework, which is specified by NAnt target framework, i.e. on .NET Framework 1.1 or .NET Framework 2.0 runtime. TeamCity 3.1. also supports test categories for task.
Shown properties can be using task of NAnt or using TeamCity system properties under runner configuration.
MSBuild Runner
Since TeamCity 3.1, the NUnitTeamCity task supports extra attributes to the NUnitTeamCity task:
Property name description Platform Specifies the desired execution mode on a x64 machine. Supported values are: x86, x64 and ANY. IncludeCategory As used in the original task
Document generated by Confluence on Jun 16, 2008 13:43 Page 139 ExcludeCategory As used in the original task NUnitVersion Specifies which version of NUnit to run the tests. Supported values are: NUnit-2.2.10 (default), NUnit-2.2.9-VSTS, NUnit-2.4.6.
TeamCity NUnit Launcher
The property is available as both environment variables and system properties of the build system (NAnt, MSTest) teamcity.dotnet.nunitlauncher — full launcher application name
TeamCity 3.1 is backward compatible to TeamCity 3.0, thus it still defines the set of properties teamcity.dotnet.nunitlauncher, but now those properties are obsolete.
The launcher supports the following command line options:
${teamcity.dotnet.nunitlauncher} [<.NET Framework>] [] [/category-include:] [/ category-exclude:] [] where
• <.NET Framework> is the version of .NET Framework to run tests. Possible values are 1.1 or 2.0. • — platform to run tests. Possible values: x86, x64 and MSIL. For .NET Framework 1.1 it is only possible to use MSIL platform. • is the test framework to use. Possible values: NUnit-2.2.10, NUnit-2.2.9-VSTS and NUnit-2.4.6 • is the list of categories separated by ';'. • is the list of assemblies paths separated by ';' or space. NUnit-2.2.9-VSTS is a modified version of NUnit to run Microsoft Visual Studio Team System Tests (for Microsoft Visual Studio 2005)
Document generated by Confluence on Jun 16, 2008 13:43 Page 140 Additional Functionality in MSBuild Scripts
This page last changed on May 06, 2008 by ivrina. Additional Functionality in MSBuild Scripts
Be sure to replace "." with "_" when using properties in MSBuild scripts. That is you have to use teamcity_dotnet_nunitlauncher_msbuild_task instead of teamcity.dotnet.nunitlauncher.msbuild.task
NUnit and NUnitTeamCity tasks
TeamCity provides additional functionality with its own NUnit and NUnitTeamCity tasks for build runners that use MSBuild scripts.
In order for these tasks to work the teamcity_dotnet_nunitlauncher system property have to be accessible. Build Agents running windows should automatically detect these properties as environment variables. If you need to set them manually, see defining agent specific properties for more information.
The NUnit/NUnitTeamCity task uses the following syntax:
The NUnit/NUnitTeamCity task tests .NET Assemblies with NUnit. Add the following code to your target in MSBuild script to implement it:
This NUnit task is automatically included in MSBuild and Solution2005 and Solution2008 builds.
TeamCity uses its own version of NUnit task for running NUnit tests. TeamCity version is compatible with the MSBuild Community Task and will issue a warning, if TeamCity does not support an attribute listed in the build script. These warnings are only for your information and will not affect the building process.
Document generated by Confluence on Jun 16, 2008 13:43 Page 141 Ant_
This page last changed on Feb 19, 2008 by chamilton.
This page is under construction.
Ant
Basic information on setting up the Ant Build Runner can be found in the Ant section of the UI Reference. This section contains additional information related to the Ant Build Runner. Support for Running Parallel Tests
By using the tag in your Ant script it is possible to have the JUnit and TestNG tasks run in parallel. TeamCity supports this and should concurrently log the parallel processes correctly.
See also:
• UI Reference: Ant
Document generated by Confluence on Jun 16, 2008 13:43 Page 142 Maven2_
This page last changed on Feb 19, 2008 by chamilton. Maven2
Basic information on setting up the Maven2 Build Runner can be found in the Maven2 section of the UI Reference. This section contains troubleshooting information related to Maven2. Solving the issue with Surefire XML Reporter
Some users complained about incorrect number of tests reported (see http://www.jetbrains.net/jira/ browse/TW-586 and http://jira.codehaus.org/browse/SUREFIRE-122). This is caused by a bug in Surefire 2.2 used in Maven 2.0.4 by default. This bug was fixed in Surefire version 2.3.
To use the new plugin version locally for a single project, you need to modify the corresponding POM file. It must contain the following code fragment within the project/build/plugins element.
Document generated by Confluence on Jun 16, 2008 13:43 Page 143 NAnt_
This page last changed on May 06, 2008 by ivrina. NAnt
Basic information on setting up the NAnt Build Runner can be found in the NAnt section of the UI Reference. This section contains information on working with the NAnt Runner. Setting the NAntHome Environment Variable
When selecting NAnt as the build runner, you need to specify the NAntHome environment variable on the agent machine with a path to the NAnt 0.85 distribution folder. This can be done by setting the environment variable on agent machine or by adding the env.NAntHome variable to the agent properties file or during the Properties and environment variables step when creating a build configuration. Please note that the variable name is case sensitive. MSBuild Task for NAnt
TeamCity NAnt runner includes a task called msbuild that allows NAnt to start MSBuild scripts. TeamCity msbuild task for NAnt has the same set of attributes as the NAntContrib package msbuild task. The MSBuild build processes started by NAnt will behave exactly as if they were launched by TeamCity MSBuild/SLN2005 build runner (i.e. NUnit and/or NUnitTeamCity MSBuild tasks will be added to build scripts and logs and error reports will be sent directly to the build server).
By default, NAnt msbuild task uses MSBuild 2.0 (from Microsoft .NET Framework 2.0), however you can use MSBuild 3.5 (from Microsoft .NET Framework 3.5) if you add the teamcity_dotnet_use_msbuild_v35 property with the value of true to your msbuild task in NAnt script. For example:
... ... ...
NUnit 2 Task for NAnt
To test all of the assemblies without halting on first failed test please use:
'failonfailureatend' attribute is not defined in the original NUnit2 task from NAnt. Note that this attribute will be ignored if the 'haltonfailure' attribute is set to 'true' for either the nuni2 element or the test element.
Document generated by Confluence on Jun 16, 2008 13:43 Page 144 See also:
• UI Reference: NAnt
Document generated by Confluence on Jun 16, 2008 13:43 Page 145 Sln2005_
This page last changed on Feb 28, 2008 by eugene petrenko. Solution 2005 Runner
.NET Testing Frameworks Support
Document generated by Confluence on Jun 16, 2008 13:43 Page 146 Sln2008_
This page last changed on Feb 28, 2008 by eugene petrenko. Solution 2008 Runner
.NET Testing Frameworks Support
Document generated by Confluence on Jun 16, 2008 13:43 Page 147 Configuring Build Triggers
This page last changed on Mar 24, 2008 by ivrina.
Configuring VCS Build Triggers Rules
VCS Build Triggers automatically start a new build each time TeamCity detects that updates have been checked into the Version Control System. By default, when this option is enabled, TeamCity scans all of the build configuration's VCS roots. TeamCity offers a wide range of wildcards and operators to exclude parts of the VCS roots or check ins performed by specific users from a VCS trigger. These rules should be entered in Build trigger rules text box.
The general syntax for a single rule is as follows:
Please refer to Ant documentation for the description of Ant-like wildcards
Please note that only "*" and "**" patterns are supported. "?" is not supported.
When entering rules please note the following:
• To enter multiple rules, each rule should be entered on a single line separated by a line feed character. • The most specific rules are applied first, regardless of the order that the rules are listed in. • As soon as you enter a "+" operator, TeamCity will remove the default include all setting. To manually reset it enter "+:**". • If you don't enter an operator it will default to "+".
• the rule "-:/src/help" excludes a build being triggered when updated files are checked into the src/ help path of the VCS root. • the rule "-:**.html" excludes all .html files from trigger a build. • the rule "-:user=techwriter;root=Internal SVN:/doc/*.xml" excludes builds being triggered by .xml files checked in by user "techwriter" to the doc path of the VCS root named Internal SVN (as defined in the VCS Settings). • the rule "-:lib/**" prevents the build from triggering by updates to the "lib" directory of the agent. All files placed into the directory (by processing VCS root checkout rules) will not cause a build to be triggered.
A VCS Root is a description (a number of connection settings) of a version control system where project sources are located.
VCS roots are configured on the Version Control Systems page of a build configuration.
Note to users upgrading from version 2.1.1 Starting with version 3.0, VCS roots are now specific to build configurations rather than projects. System time at the VCS server and the machines that check out the project sources (server or agents, depending on the value of the build configuration VCS checkout mode setting) must be synchronized. This requirement applies to CVS, Subversion, and ClearCase configurations, as well as to StarTeam if the audit is disabled or the server is older than 9.0.
Shared VCS Roots
By default, the same VCS root(s) can be used by all of the project's build configurations. They can also be used by different projects when VCS Roots Sharing is enabled on the New or Edit VCS Roots page. Sharing VCS roots saves the administrator's time and the hassle of creating and maintaining identical VCS roots in the repository.
If someone attempts to modify a VCS root that is shared, TeamCity will issue a warning that the changes to the VCS root could potentially affect more that one project. The user is then prompted to either save the changes and apply them to all the projects using the VCS root, or to make a copy of the VCS root for use by either a specific build configuration or project.
VCS Checkout Mode
The VCS Checkout mode is a configuration that sets how project sources reach an agent. Agents do not need any additional software for automatic checkout modes.
TeamCity has three different VCS checkout modes:
Checkout mode Description Automatically on server The TeamCity server will export the sources and pass them to an agent before each build. Since sources are exported rather than checked out, no administrative data is stored in the file system and version control operations (like check in or label or update) can not be preformed. Automatically on agent The build agent will check out the sources before the build. This checkout mode is supported only for CVS and Subversion. Agent-side checkout frees more server resources and provides the ability to access version control-specific directories (.svn, CVS) i.e. the build script can perform VCS operations (like check-ins into the version control) - in this
Document generated by Confluence on Jun 16, 2008 13:43 Page 149 case please ensure the build script uses necessary credentials for the check-in. Please note that "exclude" Checkout Rules cannot improve agent checkout performance because it checks out the entire included directory, then deletes the files that were excluded. Do not check out files automatically TeamCity will not check out any sources. The build script will contain the commands to check out the sources. Please note that this mode can cause TeamCity to inaccurately report changes.
VCS Checkout Rules
VCS Checkout Rules allow you to exclude paths and/or map paths (copy directories and all their contents) to a different location on the Build Agent during checkout.
To add a checkout rule click the edit checkout rules link on the build configuration's Version Control Settings page and a pop-up window will appear where you can enter the rule.
The general syntax of a single checkout rule is as follows:
+|- : VCSPath [=> AgentPath]
When entering rules please note the following:
• To enter multiple rules, each rule should be entered on a separate line. • For each file the most specific rule will apply if the file is included, regardless of what order the rules are listed in. • If you don't enter an operator it will default to +:
Rules can be used to perform the following operations:
Syntax Explanation +:.=>Path Checks out the root into Path directory -:PathName Excludes PathName (note: the path must be a directory and not a filename) +:VCSPath=>. Maps the VCSPath from the VCS to the Build Agent's default work directory VCSPath=>NewAgentPath Maps the VCSPath from the VCS to the NewAgentPath directory on the Build Agent +:VCSPath Maps the VCSPath from the VCS to the same-named directory (VCSPath) on the Build Agent
In the above example, the first rule excludes the src/help directory and its contents from checkout. The third rule is more specific than the second rule and maps the scr/samples path to the samples path in the Build Agent's default work directory. The second rule maps the contents of the scr path to the production/sources on the build agent, except src/help which was excluded by the first rule and scr/ samples which was mapped to a different location by the third rule.
Exclude checkout rules will only speed up server-side checkouts. Agent-side checkouts emulate the exclude checkout rules by checking out all the root directories mentioned as include rules and deleting the excluded directories. So, exclude checkout rules should generally be avoided for the agent-side checkout.
Document generated by Confluence on Jun 16, 2008 13:43 Page 150 VCS Labeling Support
TeamCity can optionally add a label into the version control system for the sources used for a particular build. This is useful if you need to collect all of the sources for a specific build in order to recreate it. You can choose to apply the VCS label for all builds or only for successful ones. You can also manually invoke VCS labeling action for a finished build: Check "Label this build sources" in the "VCS revisions and labels" section of the Changes tab of the build results.
The labeling process takes place after the build finish and doesn't affect the build status. If the label fails it will not change the build's status.
VCS labeling is supported for ClearCase, CVS, Perforce, StarTeam and Subversion.
• Make sure the credentials you specify allow write access to the sources repository. • Perforce roots require specification of Perforce client (not TeamCity mapping) for labeling to work. "Moving" labels (label with the same name for different builds e.g. "SNAPSHOT") are currently supported only for CVS
Subversion
Subversion VCS roots need additional configuration for VCS labeling to work. The labeling rules need to be specified to define the SVN repository structure.
Labeling rules are specified as newline-delimited rules each of uses the following format:
The repository paths can be relative and absolute (starting from "/"). Absolute paths are resolved from the SVN repository root, relative paths are resolved from the VCS root.
When creating a label, the sources residing under TrunkOrBranchRepositoryPath will be put into the tagDirectoryRepositoryPath/ directory, where is the name of the label as defined by the labeling pattern of the build configuration. If no sources match the TrunkOrBranchRepositoryPath, then no label will be created. The path tagDirectoryRepositoryPath should already exist in the repository. If tagDirectoryRepositoryPath directory already contains subdirectory with the current label name, the labeling process will fail, and the old tag directory won't be deleted or affected.
For example, there is a VCS root with the URL svn://address/root/project where svn://address/root is the repository root, and the repository has the structure:
-project --trunk --branch1 --branch2 --tags
In this case the labeling rules should be: project/trunk=>project/tags project/branch1=>project/tags project/branch2=>project/tags
See also:
• Concepts: Version Control System | VCS Root • UI Reference: Version Control Systems Configuration
Document generated by Confluence on Jun 16, 2008 13:43 Page 151 Creating and Editing Build Configurations
This page last changed on Dec 05, 2007 by mio. Creating and Editing Build Configurations
To create new build configuration for a project:
1. On the Administration page, locate the desired project in the list. 2. Click the Create build configuration link. 3. Specify the General Settings. Refer to Create or Edit Build Configuration for detailed description of the options. 4. Click the VCS settings button 5. Create/edit VCS roots and specify VCS-specific settings. See Configuring VCS Settings and Version Control Systems Configuration for additional information on CVS roots and a detailed description of the VCS configuration options, respectively. 6. Click the Build Runner button. 7. On the Choose Build Runner page, select the desired build runner from the drop-down list, and define its settings. Refer to the 3.Build Runners topic for detailed description of the runner-specific options. 8. Click Save.
To edit an existing build configuration:
1. On the Administration page, locate the desired build configuration. 2. Click the Edit link. The build configuration opens in the General Settings section of Create or Edit Build Configuration page. 3. In the General Settings page, update options as required. 4. Perform the tasks suggested in the Build Configuration Steps list, and save changes: • configure VCS settings • configure build runner • specify build triggering • configure artifact dependencies • define environment variables and properties. • specify requirements that should be met for the agents to be able to run the builds.
See also:
• System Administrator's Reference: Configuring Artifacts Dependencies| System Properties of a Build Configuration | Configuring VCS Settings • UI Reference: Administration
Document generated by Confluence on Jun 16, 2008 13:43 Page 152 Notifier Templates Configuration
This page last changed on May 07, 2008 by ivrina. Notifier Templates Configuration
In this section you can find reference information on the location and syntax of notifier templates, connection with the build events, patterns used to represent important information, and examples:
The server automatically reloads a template from the corresponding file, if it detects that this file is changed on disk.
Syntax notes
Syntax of the notifier configuration files is described in the respective *.dtd files. Notifier configuration file contains two sections:
• — notifier-specific templates with notification messages • — the list of events to be notified about, with the references to the associated templates
All templates are placed into the section, for example:
Document generated by Confluence on Jun 16, 2008 13:43 Page 153 • Jabber templates text should be placed directly into the tag. • System Tray Notifier templates must have and sub elements. The element contains template of the message and the element contains a pattern for a link corresponding to the message.
Templates are attached to the notification events. For now supported events are:
• build started (event type build_started) • build successful (event type build_successful) • build failed (event type build_failed) • build is failing (the first error notification, event type build_failing) • responsibility changes (event type responsible_changed)
If an event does not have a template attached, it is ignored, and the users will not receive notifications even if they subscribed to them.
Example of events attachment:
It is possible to attach template to a build configuration too:
In this case for the build configuration with the "Ant" id, a template with the "build_successful_ant_tpl" id will be used (if it exists). For all other build configurations default template will be used (referenced here by the "build_successful_tpl" id).
Substitution patterns
Each notification event supports its own set of substitution patterns.
The element for email notifier supports all patterns that can be used within
element for the specified event type. Additionally the {EDIT_NOTIFICATIONS_LINK} pattern is supported. This pattern is replaced with the link to the user's notification configuration page.
"build_started" event patterns
Pattern Description {PROJECT_NAME} project name {BUILD_CONFIG_NAME} build configuration name {BUILD_NUMBER} build number {CHANGES} list of first 10 changes included in the build {CHANGES_WITH_FILES} list of first 10 changes included in the build with changed files
Document generated by Confluence on Jun 16, 2008 13:43 Page 154 {AGENT_NAME} agent name where build is running {AGENT_HOST} hostname of an agent where build is running {BUILD_RESULTS_LINK} link to a build results page {BUILD_CONFIG_LINK} link to a build configuration home page
"build_successful", "build_failed" and "build_failing" events patterns
Pattern Description {PROJECT_NAME} project name {BUILD_CONFIG_NAME} build configuration name {BUILD_NUMBER} build number {SHORT_STATUS_DESCRIPTION} short description of current status: number of failed tests, number of passed tests and so on (in braces) {COMPILATION_ERRORS} compilation errors block (replaced with empty string if there were no errors) {FAILED_TESTS_ERRORS} failed tests errors block (replaced with empty string if there were no errors) {CHANGES} list of first 10 changes included in the build {CHANGES_WITH_FILES} list of first 10 changes included in the build with changed files {AGENT_NAME} agent name where build is running {AGENT_HOST} hostname of an agent where build is running {BUILD_CONFIG_LINK} link to a build configuration home page {BUILD_RESULTS_LINK} link to a build results page {BUILD_LOG_LINK} link to a build log page {BUILD_CHANGES_LINK} link to a build changes page {BUILD_ARTIFACTS_LINK} link to a build artifacts page
"responsible_changed" event patterns
Pattern Description {PROJECT_NAME} project name {BUILD_CONFIG_NAME} build configuration name {RESPONSIBLE} full name and comment of a person who took responsibility for a build failure {BUILD_CONFIG_LINK} link to a build configuration home page
Examples
Email notifier configuration
Document generated by Confluence on Jun 16, 2008 13:43 Page 155
======Configure email notifications: {EDIT_NOTIFICATIONS_LINK} Responsible for {PROJECT_NAME}::{BUILD_CONFIG_NAME} failure has been changed. Responsible for {PROJECT_NAME}::{BUILD_CONFIG_NAME} failure has been changed. Current responsible: {RESPONSIBLE}
======Configure jabber notifications: {EDIT_NOTIFICATIONS_LINK} Responsible for {PROJECT_NAME}::{BUILD_CONFIG_NAME} failure has been changed. Current responsible: {RESPONSIBLE}
Document generated by Confluence on Jun 16, 2008 13:43 Page 157
Document generated by Confluence on Jun 16, 2008 13:43 Page 158 Patterns For Accessing Build Artifacts
This page last changed on Apr 25, 2008 by ivrina. Patterns For Accessing Build Artifacts
This section covers:
• Obtaining Artifacts • Obtaining Artifacts from an Archive • Obtaining Artifacts from a BuildScript • Links to the Artifacts Containing the TeamCity Build Number
Obtaining Artifacts
Use the following patterns to download artifacts:
To download artifacts of the latest builds (last finished, successful or pinned) use the following paths:
To download artifacts by build number the following path should be used:
/repository/download/BUILD_TYPE_ID/BUILD_NUMBER/ARTIFACT_PATH where
• BUILD_TYPE_ID is a build configuration ID • BUILD_NUMBER is a build number • BUILD_ID is a build ID • ARTIFACT_PATH is a path to artifact in TeamCity server. This path may contain a {build.number} pattern , this pattern will be replaced with build number of the build whose artifact is retrieved.
Obtaining Artifacts from an Archive
TeamCity allows to obtain a file from any zip/jar archive from the build artifacts directory, using one of the following URL patterns:
• BUILD_TYPE_ID is a build configuration ID • lastFinished | lastSuccessful | lastPinned is an identifier for the build instance
Document generated by Confluence on Jun 16, 2008 13:43 Page 159 Pattern 2
/repository/archive//buildTypeId/BUILD_TYPE_ID/buildNumber/BUILD_NUMBER/ index.html where
• BUILD_TYPE_ID is a build configuration ID • BUILD_NUMBER is a build number
Obtaining Artifacts from a Build Script
It is often required to download artifacts of some build configuration by tools like wget or another downloader which does not support HTML login page. TeamCity asks for authentication if you accessing artifacts repository.
To authenticate correctly from a build script, you have to change URLs (add /httpAuth/ prefix to the URL):
Basic authentication is required for accessing artifacts by this URLs with /httpAuth/ prefix. You can use existing TeamCity username and password in basic authentication settings.
To enable downloading an artifact with guest login, you can use either way:
• Use old URLs without /httpAuth/ prefix, but with added guest=1 parameter. For example:
In this case you will not be asked for authentication.
Links to the Artifacts Containing the TeamCity Build Number
You can use {build.number} as a shortcut to current build number in the artifact file name. For example: http://teamcity.yourdomain.com/repository/download/bt222/.lastFinished/TeamCity-{build.number}.exe
Document generated by Confluence on Jun 16, 2008 13:43 Page 160 System Properties for Running the Server
This page last changed on May 08, 2008 by yaegor. System Properties for Running the Server
Various aspects of TeamCity's behavior can be customized through a set of JVM options. The options can be specified using the -D parameter passed to the JVM running the TeamCity server or agent. e.g.
-Dteamcity_logs=../logs/
• If you run the server using the runAll or teamcity-server scripts, you can set the options via TEAMCITY_SERVER_OPTS environment variable. • If you run the server as Windows service, run Tomcat's service configuration editor by entering the command TeamCity/bin/tomcat6w.exe //ES//TeamCity and edit the Java Options on the Java tab (for more information see Tomcat 6 documentation). Server-only Properties
Property Name Description teamcity.data.path Edit this property to modify default location of TeamCity data directory modification.check.interval Number of seconds between successive polling of VCS servers (TeamCity 3.0 has a default value of 60). The interval's time starts being counted as soon as the last VCS server poll is finished. Since TeamCity 3.0 this property can be edited in the web UI on Administration > Server Configuration page Server and Agent Properties
Property Name Description log4j.configuration The URL of the log4j.xml file to be used for logging in TeamCity (applies both to agent and server). For example:
-Dlog4j.configuration=file:../conf/teamcity- server-log4j.xml teamcity_log When the default teamcity-(server/agent)- log4j.xml is used, this specifies the directory which will contain TeamCity logs. By default it points to /logs or /logs, respectively. Other Server Configurations
Turning off code highlighting in the web diff
The highlighting uses a third-party native library that may not be available for your platform. If TeamCity fails to cope with this or the library causes unstable behavior on the server, you can disable the use of this library.
To disable the Colorer library:
1. Edit \webapps\ROOT\WEB-INF\buildServerSpringWeb.xml and change the "enableColorer" property value to false by locating the following fragment:
Document generated by Confluence on Jun 16, 2008 13:43 Page 161
and changing it to
2. Restart the server.
Document generated by Confluence on Jun 16, 2008 13:43 Page 162 System Properties of a Build Configuration
This page last changed on May 07, 2008 by ivrina. System Properties of a Build Configuration
Various build configuration settings can be defined by referencing Build Configuration Properties. Build Configuration Properties are either user-defined or predefined.
The system properties and environment variables required for a build configuration can be defined in three locations. Where these properties and variables are set will determine whether they affect a specific build configuration, all of a project's build configurations that use the same VCS root, or a specific Build Agent.
• To define properties specific to a build configuration, enter them on the Build Configuration's Properties and environment variables page. • To define properties for all of a project's build configurations that use the same VCS root, create a text file named teamcity.default.properties, and check it into the VCS root. Ensure the file appears directly in the build working directory by specifying appropriate checkout rules. The name and path to the file can be customized via the teamcity.default.properties property of a build configuration. Properties defined this way will not be visible in the TeamCity web UI, but will be passed directly to the build process. • To define agent-specific properties edit the Build Agent's buildAgent.properties file (/conf/buildAgent.properties). (see Agent-specific below) Note that properties and variables entered on the build configuration's page take priority and will supersede the values entered in the teamcity.default.properties and buildAgent.properties files. Likewise values set in the buildAgent.properties file will supersede values set in the teamcity.default.properties. Default build properties loaded from teamcity.default.properties are logged into the agent's log, but not to the build log. The system properties and environment variables are defined in the teamcity.default.properties and buildAgent.properties files using the following format:
[env|system].property_name=property_value For example: env.CATALINA_HOME=C:\tomcat_6.0.13
• env. properties define the environment variables used during the process of running the build. These consist of the environment variables of the agent running the build, the environment variables defined in the agent configuration and the TeamCity default properties files and the environment variables set for the build configuration on the Properties and environment variables page when you create or edit a build configuration. Please note that the agent's environment variables can vary depending upon which user the agent process is running. The list of environment variables available on a specific build agent can be found on the Environment variables tab of the Agent Details page . • system. properties include the properties defined on the Properties and environment variables page in build configuration area of TeamCity, agent-specific predefined properties as well as system properties defined in the agent configuration file.
Document generated by Confluence on Jun 16, 2008 13:43 Page 163 Referencing Properties
On the build configuration administration screens the properties can be referenced by %system.% and %env.%. Only the properties defined on agent and in the build configuration itself can be referenced.
Any user-defined property can reference other properties by using the following format:
%[env|system].property_name% For example: system.tomcat.libs=%env.CATALINA_HOME%/lib/*.jar
An exception to this is the teamcity.build.checkoutDir, which is referenced as is, without prefixes.
Any Global and system property (system.*) can be referenced in a build script by the property name:
• For Ant and NAnt use ${} • For MSBuild (Visual Studio 2005/2008 Project Files) use $() Don't forget to leave the "system." part out of the system properties.
When using MSBuild, remember to replace "." with "_" when you reference property names.
Any user-defined environment variable is passed to the environment of the build agent that will process the build and can be used there as a usual environment variable.
Any property that is referenced in a build configuration, but is not defined, becomes a requirement for the configuration. The build configuration will be run only on agents that have this property defined.
Predefined Properties
Global
These properties can be used for setting various build configuration settings and inside build scripts.
Property Name Value teamcity.build.checkoutDir working folder where the build is started build.number build number assigned by TeamCity build.vcs.number.XX VCS changelist number, where XX is the number of VCS root (1, 2, etc.) Use build.vcs.number.1 if only one VCS root is configured for a project Please note that this value is VCS-specific (e.g. for SVN the value is a revision number)
For a full list of supported properties please refer to the Properties and environment variables section of Build Configuration settings in TeamCity Web UI.
Agent-specific
Agent-specific properties are defined on each build agent and vary depending on its environment. Aside from standard properties (for example os.name or os.arch, etc. — these are provided by JVM running on agent) agents also have properties based on installed applications. TeamCity automatically detects a number of applications including the presence of .NET Framework, Visual Studio, and TeamCity NUnitLauncher utility and adds the corresponding system properties and environment variables. (A complete list of predefined properties is provided in the table and list below). If additional applications/ libraries are available in the environment, the administrator can manually define the property in the buildAgent.properties file (/conf/buildAgent.properties). These properties can be used for setting various build configuration options, for defining build configuration requirements (e.g.
Document generated by Confluence on Jun 16, 2008 13:43 Page 164 existence or lack of some property) and inside build scripts. For more information on how to reference these properties see Referencing prosperities above.
Predefined Property Description agent.name Name of the agent as specified in the buildAgent.properties agent configuration file. Can be used to set a requirement of build configuration to run (or not run) on particular build agent. DotNetFramework[_x86|_x64] This property is defined if the corresponding version(s) of .NET Framework is installed DotNetFramework[_x86|_x64]_Path This property's value is set to the corresponding framework version(s) path(s) DotNetFrameworkSDK[_x86|_x64] This property is defined if the corresponding version(s) of .NET Framework SDK is installed DotNetFrameworkSDK[_x86|_x64]_Path This property's value is the path of the corresponding framework SDK version WindowsSDK This property is defined if the corresponding version of Windows SDK is installed. Version can be either 6.0 or 6.0A VS[2003|2005|2008] This property is defined if the corresponding version(s) of Visual Studio is installed VS[2003|2005|2008]_Path This property's value is the path to the directory that contains devenv.exe teamcity.dotnet.nunitlauncher This property's value is the path to the directory that contains the standalone NUnit test launcher, NUnitLauncher.exe. The version number refers to the version of .NET Framework under which the test will run. The version equals the version of .NET Framework and can have a value of 1.1, 2.0, or 2.0vsts. teamcity.dotnet.nunitlauncher.msbuild.task The property's value is the path to the directory that contains the MSBuild task dll providing the NUnit task for MSBuild, sln2005, or sln2008. Please note:
• Make sure to replace "." with "_" when using properties in MSBuild scripts. That is use teamcity_dotnet_nunitlauncher_msbuild_task instead of teamcity.dotnet.nunitlauncher.msbuild.task • _x86 and _x64 property suffixes are used to designate the specific version of the framework. • teamcity.dotnet.nunitlauncher properties can not be hidden or disabled.
Here is the complete list of supported predefined properties:
You can disable the autodetection of these predefined properties by editing the buildAgent.properties file and adding the disableDotNetDetection property. Please note that this property is case-sensitive.
This property can have the following values:
Value Description empty string All versions of .NET Framework will be detected and added to the Agent's properties '*' All existing versions of .NET Framework will not be detected and thus not included in the Agent's Properties version number(s) (Values should be separated by Excludes versions of .NET Framework starting with commas) that number 'windowsSDK6.0' or 'w' Excludes Windows SDK 6.0 VS Excludes Visual Studio version , where can be 2003, 2005, 2008 or left blank to exclude all existing versions of Visual Studio Examples Description disableDotNetDetection=3 Excludes .NET Framework 3.0, 3.5 and all other versions starting with 3 disableDotNetDetection=1.1,2.0 Excludes .NET Framework versions 1.1 and 2.0 disableDotNetDetection=w,2.0,VS2003 Excludes Windows SDK 6.0, .NET Framework 2.0 and Visual Studio 2003 Please refer to the Agent Details page of the TeamCity web UI to view a particular Build Agent's properties.
See also:
• System Administrator's Reference: .NET Testing Frameworks Support
Document generated by Confluence on Jun 16, 2008 13:43 Page 166 Third-Party License Agreements
This page last changed on May 16, 2008 by yaegor. Third-Party License Agreements
The following is an alphabetical list of third-party libraries distributed with TeamCity:
Product License Acegi Security Apache Apache Ant Apache Apache Commons libraries Apache Behaviour BSD Colorer Mozilla cglib Apache CVS client library CDDL CyberNekoHTML Parser Apache-style DbUnit GNU LGPL Expat XLM Parser Toolkit MIT FormattedDataSet API BSD FreeMarker BSD-style Ganymed SSH-2 for Java BSD-style Google Collections Library Apache HSQLDB BSD Ivy Apache Jakarta Apache Jakarta-ORO Apache JAMon BSD-like Java Native Access LGPL Java Service Wrapper, version 3.2.3 Java Service Wrapper License JCIFS GNU LGPL JDom JDom JFreeChart GNU LGPL jMock jMock JNIWrapper JNIWrapper Joda Time Apache JUnit CPL Log4j Apache Log4net Apache Maven Apache Maverick MIT/Apache NanoContainer NanoContainer Nifty Corners Nifty Corners NUnit 2.2.x NUnit NUnit 2.4.x NUnit pack:tag LGPL Paul Johnson's MD5 BSD PicoContainer PicoContainer PocketHTTP Mozilla PocketXML-RPC Mozilla PostgreSEL Data Base Management System BSD Prototype MIT Rome Apache Script.aculo.us MIT License SilverStripe Unobtrusive Javascript Tree Control BSD Shaj Apache Smack Apache Spring Framework Apache SVNKit TMate Open Source Tomcat Apache Tom Wu's jsbn BSD Trove4j GNU LGPL
Document generated by Confluence on Jun 16, 2008 13:43 Page 167 Xerces2 Java Parser Apache XML Pull Parser IU Extreme! Lab XML-RPC.NET MIT X11 XStream XStream Acknowledgements
Document generated by Confluence on Jun 16, 2008 13:43 Page 168 Troubleshooting
This page last changed on Feb 11, 2008 by chamilton. Troubleshooting
When problems occur, there are a number of places to check for information after you've determined the problem isn't your setup.
• Known Issues: Check the known issues section of the documentation.
• TeamCity's Issue Tracker - Browse the issue tracker to see if your problem has already been reported. If it has, be sure to vote for that issue.
• The TeamCity Forum - Check the forum to see if anyone else has experienced your problem. The forum has an active user base and is a good place to find support.
If you're still unable to resolve your issue then review the information in the Reporting Issues section the in documentation, collect logs and events and submit them to the development team.
See also:
• System Administrator Reference: Known Issues | Reporting Issues
Document generated by Confluence on Jun 16, 2008 13:43 Page 169 Known Issues
This page last changed on May 16, 2008 by yaegor. Known Issues
This page contains a list of workarounds for known issues in TeamCity.
If you experience strange web UI issues that are not reproduced on other computers, please make sure your browser is not using cached versions of content. This can be achieved by clearing browser caches. Logging with Log4J in your tests
If you use Log4J logging in your tests, in some cases you may miss Log4J output from your logs. In such cases, please do the following:
• Use Log4J 1.2.12 and you're done • For Log4J 1.2.13+, add parameter "Follow=true" for console appender, used in Log4J configuration:
Code Snapshots Highlighting
The code snapshots displayed in the diff view and duplicates code fragments are highlighted using Colorer native library. For the time being the library does not support 64 bit platforms. However, this can be workarounded by running TeamCity server under 32 bit JVM in 64 bit OS. NUnit 2.4.6 Performance
Due to an issue in NUnit 2.4.6 (bundled), it's performance may be slower than NUnit 2.4.1. For additional information, please refer to the corresponding issue in our tracker: TW-4709 StarTeam Performance
Using StarTeam SDK 9.0 instead of StarTeam SDK 9.3 on the TeamCity server can significantly improve VCS performance when there is a slow link between TeamCity and StarTeam servers. Agent service can exit on user logout under Windows x64
Used version of Java Service Wrapper does not fully support Windows 64 and this causes agent launcher process to be killed on user logout. The agent itself will be functional until next restart (server upgrade or agent properties change).
Document generated by Confluence on Jun 16, 2008 13:43 Page 170 Reporting Issues
This page last changed on May 16, 2008 by yaegor. Reporting Issues
If you experience problems running TeamCity and believe it's related to the software, please contact us with detailed description of the issue. You can post an issue into publicly available issue tracker. Or write us an e-mail
To fix a problem, we may need a wide range of information about your system and various logs. The information below will help explain how to collect this information from your system when you are having trouble.
In this section:
• Logging • Hangs and thread dumps • OutOfMemory problems • Version Control Debug Logging • Patch Application Problems • Remote Run Problems • Server Performance • Sending Large Files to the Developers
Logging
TeamCity (both server and build agents) logs events and warnings using log4j.
The logging rules and log4j configuration files for TeamCity are described in Logs of Internal Events.
By default, log4J configuration file is /conf/teamcity-server-log4j.xml for the server, and /conf/teamcity-agent-log4j.xml for build agents. These default settings are used if TeamCity server is installed from Windows distributions or is run by runAll startup script. If you start the web server using your own script make sure you pass -Dlog4j.configuration=file:../conf/ teamcity-server-log4j.xml -Dteamcity_logs=../logs/ JVM options.
Before reproducing the problem it makes sense to enable 'DEBUG' log level for TeamCity classes. To do it, change the following section in teamcity-(server|agent)-log4j.xml files:
After that, DEBUG messages will go to teamcity-*.log files.
There are also more specific logs that can be enabled by removing comments in the file (marked with string).
Make sure the logs are not rotate too quickly. When debug is enabled it makes sense to increase maxBackupIndex value in the relevant appender tag to 10 or even 20 files (ensure there is sufficient free disk space available)
You can change the log4J configuration files while the server/agent is running. If it is possible (some log4j restrictions apply), the loggers will be reconfigured without process restart.
Document generated by Confluence on Jun 16, 2008 13:43 Page 171 Hangs and thread dumps
If you experience problems with the TeamCity server (e.g. no responding or working too slow) we would appreciate a thread dump of the server process.
• On Windows, press Ctrl+Break in console window. • On Linux, run 'jstack ' or 'kill -3 '. Output will appear in /logs/catalina.out.
In GUI mode, you can also use AdaptJ StackTrace Utility under Windows, Linux or Mac OS X to get the stacktrace of the process even if it runs without console.
See also Server Performance section below.
OutOfMemory problems
If you experience problems with TeamCity "eating" too much memory (OutOfMemory errors), please do the following:
• determine what process encounters the error (the actual building process, the TeamCity server, or the TeamCity agent) • try to increase the memory for the process via '-Xmx' JVM option, like -Xmx512m. The option needs to be passed to the process with problems: ° if it is the building process itself, use "JVM Command Line Parameters" settings in the build runner. e.g. Inspections builds may specifically need to increase the parameter; ° if it is TeamCity server, modify runAll.* script or (if server is run as Windows service), use TeamCity/bin/tomcat5w.exe //ES//TeamCity (see more); ° if it is TeamCity build agent, modify agent.* script • if increasing memory does not help, please get the memory dump and send it to us for further analysis: ° to get a memory dump (hprof file) when an OOM error occurs, please add the following JVM option (works for JDK 1.5.0_07+): -XX:+HeapDumpOnOutOfMemoryError ° when OOM error occurs next time, java_xxx.hprof file will be created in the process startup directory (TeamCity/bin or buildAgent/bin); ° please archive the file and send it to us.
Version Control Debug Logging
There are a set of debug options that turn on debug logging for specific version controls. Run the server with the required option and send us teamcity-vcs.log file for analysis. Some version controls also have specific logs that appear after uncommenting corresponding sections form the log4j configuration file.
Some options need to be specified as JVM parameters. For description of more JVM parameters and how to add them see System Properties for Running the Server section.
SVN Debug Logging
Adjust the logging configuration and restart the server or agent, correspondingly. The log will be saved to the logs\teamcity-svn.log file.
Agent
To turn on debug logging of the SVNkit library on the server side, uncomment the lines marked with in the \conf\teamcity-server-log4j.xml file. In TeamCity version prior to 3.1, perform the instructions to enabling debug on agent, but in \conf\teamcity-server-log4j.xml file.
Server
To turn on debug logging of the SVNkit library on the agent (only relevant for agent-side checkout mode) uncomment the following lines in the \conf\teamcity-agent-log4j.xml file:
Document generated by Confluence on Jun 16, 2008 13:43 Page 172
CVS
Use -Dcvs.log.commands=true JVM parameter
ClearCase
Use -Dcc.log.commands=true JVM parameter ClearCase commands with their output will be stored into ClearCase.log file in the server working directory.
Patch Application Problems
In case server-side checkout is used, the "patch" that is passed from server to the agent can be retrieved by:
• add property agent.save.patch=true to the build configuration properties: Administration->Edit configuration->Properties and requirement variables->Add new property... • trigger the build.
Agent log will contain the line "Patch is saved to file ${file.name}" Get the file and provide it with the problem description.
Remote Run Problems
The changes that are sent form the IDE to the server on a remote run can be retrieved from server's .BuildServer\system\changes directory. Locate the .changes file that corresponds to your change (you can pick the latest number available or deduce the from the URL of the change form the web UI). The file contains the patch in the binary form. Please provide it with the problem description.
Server Performance
If you experience degraded server performance and TeamCity server process is producing large CPU load, please take the CPU profiling snapshot and send it to us accompanied with the detailed description of what you were doing and what is your system setup.
You can take the CPU profiling and memory snapshots by installing the server profiling plugin and following the instructions provided on the plugin page. Logging in TeamCity Visual Studio plugin
To capture logs from TeamCity Visual Studio plugin please do the following:
1. Close all instances of Visual Studio 2. Open \Local Settings\Temp\JetLogs folder 3. Delete all of the files in this folder 4. Restart Visual Studio 5. Open a solution 6. Try to log in to TeamCity 7. Close Visual Studio 8. Navigate back to the \Local Settings\Temp\JetLogs folder. All of the files that were created are logs.
Document generated by Confluence on Jun 16, 2008 13:43 Page 173 Sending Large Files to the Developers
Files under 5Mb in size can be attached right into the tracker issue. If you do not want the content of the files be publicly available or the file is over 5 Mb, you can upload the archived files to ftp://ftp.intellij.net/.uploads and let us know the exact file name.
Document generated by Confluence on Jun 16, 2008 13:43 Page 174 UI Reference
This page last changed on Apr 24, 2008 by ivrina. UI Reference
This part contains detailed descriptions of the tabs and controls of the TeamCity user interface.
Item Description Projects Use this page to view the list of projects and their build configurations, view build results, and download artifacts. Build configurations can be expanded to show the status of running builds and the last completed build. My Changes Use this page to view the changes during the last 5 days when the current user was active and introduced changes, already included in builds. Agents Use this page to view the list of agents within the build grid, enable or disable agents, view and change settings of a specific agent, enable clean sources, and view build results. Build Queue Use this page to manage the order of builds in queue, and view the details of compatible and incompatible agents. Administration Use this page to view and edit projects, build and server configurations, VCS roots, user accounts, clean-up policies, and licenses. My Settings & Tools Use this page to configure the visible projects, set up notifiers, view and edit version control authentication settings, and install TeamCity tools. Search Use this field to find builds by number, tag, or build configuration name. You can type several keywords to get more precise results, for example: #3453 Selena. TeamCity 3.1+ supports searching for builds that were performed by a specific build agent. Type @ (e.g. @unit01) and a popup list of all the builds that were performed by the agent (that haven't been cleaned-up) will appear.
Document generated by Confluence on Jun 16, 2008 13:43 Page 175 Administration
This page last changed on Apr 24, 2008 by ivrina. Administration
This section provides descriptions of the controls on the Administration tab.
The Administration tab is only available for the users who have permissions of a System Administrator or Project Administrator for at least one project.
• Projects and Build Configurations • Administration Side Bar
Projects and Build Configurations
Item Description Projects and build configurations Each project is represented as a table that contains the list of its build configurations. Create project Click this link to create a new TeamCity project. See Create New Project. Edit Click this link to modify settings of the selected project of build configuration. See Create or Edit Build Configuration and Create New Project. Copy Click this link to create a clone of the selected project or build configuration, and then modify it. See Create or Edit Build Configuration and Edit Project. Create build configuration Click this link to add a new build configuration. See Create or Edit Build Configuration.
Administration Side Bar
Item Description VCS roots Click the Configure VCS roots link to view and edit version control system settings used by TeamCity. See VCS Roots. Build History Clean-up Click the Configure clean-up policy link to define a number of builds and the time to preserve them in the build history. See Build History Clean-Up Policy. Server Configuration Click the Edit server configuration link to view and change server settings. See Edit Server Configuration. User Account Click the Configure user accounts link to add new users, delete user accounts, or change settings of the existing users. See User accounts. Licenses Click the Manage licenses link to view information about available licenses, and add new licenses. See Licenses.
See also:
• Concepts: Account | Role | Permission
Document generated by Confluence on Jun 16, 2008 13:43 Page 176 Build History Clean-Up Policy
This page last changed on Apr 24, 2008 by ivrina. Build History Clean-Up Policy
Administration > Configure clean-up policy
Please note that the page was restructured between versions 3.0 and 3.1. Refer to the applicable description: 3.0 or 3.1. The Build History Clean-up Policy Page in Version 3.0
On this page you can enable or disable the clean-up process, set up its timing, and configure the clean-up policy for various build configurations. The page also informs you about the next scheduled clean-up, and the duration of the last clean-up.
Option Description Enable/Disable If the clean-up policy is disabled, the page is blank, and Enable button is available. If clean-up policy is enabled, this page displays the list of build configurations that have a clean-up policy. Clean-up policy settings Use the following fields to create the clean-up schedule. Clean-up start time Use the drop-down list to select the start time using the hh:mm format Save Click this button to save the start time settings. Start clean-up now Click this button to launch clean-up immediately. Configure clean-up policy Use this table to view the list of build configurations with their clean-up rules, edit or delete clean-up rules. Edit Click this link to open Edit Clean-up rule dialog. Delete Click this link to delete the selected rule. Add clean-up rule Click this button to create a new rule. See Add/Edit Clean-up rule dialog.
Add / Edit Clean-Up Rule Dialog
Option Description Apply to Use this combo box to select the build configuration, to which the rule will apply. Keep history for ... days Check this option, if you want to preserve the build history, and specify the number of days. Keep not less than ... successful builds in history Check this option, if you want to preserve certain amount of successful builds, and specify the number of builds to be kept. Save Click this button to save changes and close the dialog.
The Build History Clean-up Policy Page in Version 3.1
On this page you can enable or disable the clean-up process, set up its timing, and configure the clean-up policy for various build configurations. The page also informs you about the next scheduled clean-up, and the duration of the last clean-up.
Option Description Enable/Disable If the clean-up policy is disabled, the page is blank, and Enable button is available. If clean-up policy
Document generated by Confluence on Jun 16, 2008 13:43 Page 177 is enabled, this page displays the list of build configurations that have a clean-up policy. Clean-up policy settings Use the following fields to create the clean-up schedule. Clean-up start time Use the drop-down list to select the start time using the hh:mm format Save Click this button to save the start time settings. Start clean-up now Click this button to launch clean-up immediately. Configure clean-up policy Use this table to view the list of build configurations with their clean-up rules, edit or delete clean-up rules. Edit Click this link to open Edit Clean-up rule dialog. Delete Click this link to delete the selected rule. Add clean-up rule Click this button to create a new rule. See Add/Edit Clean-up rule dialog.
Add / Edit Clean-Up Rule Dialog
Option Description Apply to builds of Use this combo box to select the build configuration(s), to which the rule will apply. Data to clean Select one of the following radio buttons to choose the data that will be removed during clean-up. Remove artifacts, but keep history and statistical Select this option to only remove artifacts from the data build history. Remove builds from history but keep statistical data Select this option to remove the builds (including artifacts) but retain statistical information. Remove everything Select this option to remove everything from the build history. Data will be removed from builds that are Select the appropriate check box(es). Note that one check box must be selected and that if both options are selected, only the builds that meet both conditions will be affected. More than ... days older that the last build Check this option to preserve the above selected data for a duration of time; select this option and specify the number of days. A day is equivalent to a 24-hour period, not a calendar day. Older than the ...-th successful build Check this option to preserve a certain amount of successful builds (and all the failed builds between them); specify the number of successful builds to be kept. Save Click this button to save changes and close the dialog.
See also:
• Concepts: Clean-Up Policy
Document generated by Confluence on Jun 16, 2008 13:43 Page 178 Create Edit Build Configuration
This page last changed on Dec 05, 2007 by mio. Create or Edit Build Configuration
Administration > Create build configuration
Administration > > Create build configuration
Projects > > Edit Configuration Settings
• Common #ontrols • Build Configuration Steps Common Controls
Administration> project name > build configuration View the name of the project, and the name of the name build configuration. Click the Run button to start a build on the next available agent. Click the drop-down arrow on the right side of the Run button to view a drop-down list of compatible Build Agents. Use this list to select a specific agent to run the build. Build Configuration Home Click this link to open the Build Configuration home page. Copy Create a clone of this configuration. Delete Delete this configuration and all related information. Save Save changes
Build Configuration Steps
You can navigate to and edit any part of the project by using the following buttons which appear on the right side of the build configuration pages.
Item Description General Settings Click this button to define general settings of the build configuration on the General Settings page. VCS Settings Click this button to edit, add or detach VCS roots and configure the VCS settings on the VCS settings page. Runner: Click this button to define the build runner settings on the Build Runner page. Contents of the page depends on the selected build runner. Build Triggering Click this button to configure the build triggering options on the Build Triggering page. Artifact Dependencies Click this button to configure dependencies on the Artifact Dependencies page. Properties and Environment variables Click this button to view existing build configuration system properties and environment variables, and define new ones on the System Properties and Environmental Variables page. Agent requirements Click this button to view and manage requirements to the agents, and see the list of agents that meet or do not meet these requirements on the Agent Requirements page.
Document generated by Confluence on Jun 16, 2008 13:43 Page 179 1.General Settings
This page last changed on May 20, 2008 by ivrina. General Settings
Administration > project > build configuration > General Settings
Please note that the page was restructured between versions 3.0 and 3.1. Refer to the applicable description: 3.0 or 3.1. The General Settings Page in Version 3.0
Item Description Name Edit the name of the build configuration. The build configuration name should not contain special characters. Description Enter an optional description. Build options Specify behavior of the builds of this build configuration. The possible options are:
• Clean all files before build: Check this option to remove all of the residual information left by the build runner that might impede the next build of the same configuration. If this option is checked, TeamCity performs a full checkout of the entire project before each build. • Fail build if at least one test failed: Check this option to mark the build as failed, if the build fails at least one test. If this option is not checked, the build can be marked successful even if it fails to pass a number of tests. • Enable execution timeout: Check this option to enable time control of the build. If the specified period of time in minutes is exceeded, the build is automatically canceled. This option helps you deal with builds that hang and maintains agent efficiency. • Number of simultaneously running builds: Specify the number of builds of the same configuration that can run simultaneously on all agents. This option helps avoid the situation, when all of the agents are busy with the builds of a single project. Build numbering format Specify the build numbering format. The pattern can refer to:
• build counter: pattern {0} is replaced with increasing build counter value. • VCS changeset: pattern {build.vcs.number.1}is replaced with actual changeset number from the VCS. Since TeamCity supports several version control systems for each project, there could be {build.vcs.number.2} etc, depending on the number of source control systems used by the project. Example 1.0.{0}.{build.vcs.number.1}
Document generated by Confluence on Jun 16, 2008 13:43 Page 180 Build counter Specify the counter to be used in the build numbering. Each build increases the build counter by 1. Reset counter Specify the starting number. Use the Reset counter link to reset counter value to 1. Enable status widget Check this option to enable retrieving the status of the latest build to an external web page. See Enabling the Status Widget for Build Configurations.
The General Settings Page in Version 3.1
Item Description Name Edit the name of the build configuration. The build configuration name should not contain special characters. Description Enter an optional description. Build number format Specify the build number format. The pattern can refer to:
• build counter: pattern {0} is replaced with increasing build counter value. • VCS changeset: pattern {build.vcs.number.1}is replaced with actual changeset number from the VCS. Since TeamCity supports several version control systems for each project, there could be {build.vcs.number.2} etc, depending on the number of source control systems used by the project. Example 1.0.{0}.{build.vcs.number.1} Build counter Specify the counter to be used in the build numbering. Each build increases the build counter by 1. Reset counter Specify the starting number. Use the Reset counter link to reset counter value to 1. Artifact paths Use this field to specify directories containing artifacts or file names as a comma-separated string. If a directory is specified its contents will be uploaded to the server. Fail build if Specify how TeamCity should fail builds. The possible options are:
• build process exit code is not zero: Check this option to mark the build as failed if the build process doesn't exit successfully. • at least one test failed: Check this option to mark the build as failed if the build fails at least one test. If this option is not checked, the build can be marked successful even if it fails to pass a number of tests. • an error message is logged by build runner: Check this option to mark the build as failed if the build runner reports an error while building. • it runs longer than ... minutes: Check this option and enter a value in minutes to enable time control on the build. If the specified amount of time is exceeded, the build is automatically canceled. This option helps to deal with builds that hang and maintains agent efficiency.
Document generated by Confluence on Jun 16, 2008 13:43 Page 181 Build options Specify additional options for the builds of this build configuration. The possible options are:
• Enable status widget: Check this option to enable retrieving the status of the latest build to an external web page. See Enabling the Status Widget for Build Configurations. • Limit the number of simultaneously running builds: Specify the number of builds of the same configuration that can run simultaneously on all agents. This option helps avoid the situation, when all of the agents are busy with the builds of a single project. Enter 0 to allow an unlimited number of builds to run simultaneously.
See also:
• Concepts: Build Configuration • System Administrator's Reference: Enabling the Status Widget for Build Configurations • UI Reference: Administration
Document generated by Confluence on Jun 16, 2008 13:43 Page 182 2.Version Control Settings
This page last changed on Jan 31, 2008 by chamilton. Version Control Settings
Administration > > > Version Control Settings or Administration > Configure VCS roots > > Version Control Settings
This page describes the options available on the Version Control Settings page when editing build configurations. VCS Roots
Option Description A table of existing VCS roots will appear if they are already attached to the build configuration. Click the name or edit to modify it, detach to remove the VCS root from build configuration (it will not be deleted from the project). Click edit checkout rules to view or change the selected VCS root's checkout rules. Attach existing VCS root This item will appear if the project contains VCS roots that are not already attached to the particular build configuration. Select the VCS root from the drop-down list to attach it to the build configuration and add it to the table listed above. Create and attach new VCS root Click this link to attach a new VCS root. You will be redirected to the create VCS root page. Checkout Settings
Option Description VCS checkout mode Select the desired VCS checkout mode from the drop-down list. Options include: Automatically on server (the TeamCity server will check out the sources and pass them to an agent before each build), Automatically on agent (the build agent will check out the sources before the build), and Do not check out files automatically (TeamCity will not check out any sources. The build script will contain the commands to check them out). Note: Agent-side checkout is only supported for CVS and Subversion. Checkout directory Specify the directory on the agent where you want the sources to be checked out to and the build process to start. Leave this field blank to use the agent's default Build Checkout Directory. Clean all files before build Check this option to remove all of the residual information left by the build runner that might impede the next build of the same configuration. If this option is checked, TeamCity performs a full checkout of the entire project before each build. This feature is located on this page in TeamCity 3.1+. If you are using version 3.0 please look for this option under build options on the General Settings page. If you use several VCS roots for a single build configuration, you will probably need to configure VCS checkout rules to specify to which directory each root will be checked out.
Document generated by Confluence on Jun 16, 2008 13:43 Page 183 VCS Labeling
Option Description VCS labeling mode Click a radio button to choose the VCS labeling mode. The possible options are:
• Do not label: disable labeling • Successful only: label successful builds only • Always: label all builds Labeling pattern This field can be edited if VCS labeling is enabled. The label consists of the build name and number using the following format: %system.build.number%. Choose VCS roots to label Check each build configuration to be labeled.
Changes Checking Interval
Option Description Checking interval Select a radio button to choose between the global server setting of 60 seconds and entering a custom interval. Some public servers block access if polled frequently. VCS Root Sharing
Option Description VCS Root Sharing Enable this option to use this VCS root in other projects or build configurations. See Shared VCS Roots for more information.
See also:
• Concepts: Version Control System | VCS Root • Administrator's Reference: Configuring VCS Settings • UI Reference: Version Control Settings | New Edit VCS Roots
Document generated by Confluence on Jun 16, 2008 13:43 Page 184 ClearCase
This page last changed on Nov 20, 2007 by chamilton. ClearCase
This page contains descriptions of the fields and options available when setting up VCS roots using the ClearCase Version Control System. ClearCase Settings
Option Description View path Path to project sources inside some specified view. Do not use view you're working with because TeamCity calls update before checking for changes and building patch and it might lead to problems with checking in changes. Use ClearCase Use the dropdown menu to select either UCM or BASE. Make sure that the user that runs the TeamCity server process is also a ClearCase view owner.
Changes Checking Interval
Option Description Checking interval Select a radio button to choose between the global server setting of 60 seconds and entering a custom interval. Some public servers block access if polled frequently. VCS Root Sharing
Option Description VCS Root Sharing Enable this option to use this VCS root in other projects or build configurations. See Shared VCS Roots for more information.
See also:
• Concepts: Version Control System | VCS Root • Administrator's Reference: Configuring VCS Settings • UI Reference: Version Control Settings | New Edit VCS Roots
Document generated by Confluence on Jun 16, 2008 13:43 Page 185 CVS
This page last changed on Apr 25, 2008 by ivrina. CVS
This page contains descriptions of fields and options available when setting up a VCS root using CVS. Depending on the selected access method, the page shows different fields, that help you to easily define the CVS settings. Common options
Option Description Module name Specify the name of the module managed by CVS. CVS Root Use these fields to select the access method, point to the user name, CVS server host and repository. For example: ':pserver:[email protected]:/ repository/path'. For a local connection only the path to the CVS repository should be used. TeamCity supports the following connection methods:
• pserver • ext • ssh • local Checkout Options Click one of the radio buttons to define the way CVS will fill in and update the working directory. The following options are available:
• Checkout HEAD Revision • Checkout from Branch • Checkout by Tag Quiet Period Specify a period of time in seconds that CVS should be inactive (no commits) before a build should start.
PServer Protocol Settings
Option Description CVS Password Click this radio button if you want to access the CVS repository by entering password. Password File Path Click this radio button to specify the path to the .cvspass file. Connection Timeout Specify connection timeout. Proxy Settings Specify the proxy settings. Use proxy Check this option if you want to use a proxy, and select the desired protocol from the drop-down list. Proxy Host Specify the name of the proxy. Proxy Port Specify the port number. Login Specify the login name. Password Specify the password.
Ext Protocol Settings
Option Description
Document generated by Confluence on Jun 16, 2008 13:43 Page 186 Path to external rsh Specify the path to the rsh program used to connect to the repository. Path to private key file Specify the path to the file that contains user authentication information. Additional parameters Enter any required rsh parameters that will be passed to the program. Multiple parameters are separated by spaces.
SSH Protocol Settings (internal implementation)
Option Description SSH version Select a supported version of SSH. SSH port Specify SSH port number. SSH Password Click this radio button if you want to authenticate via an SSH password. Private Key Click this radio button to use private key authentication. In this case specify the path to the private key file. SSH Proxy Settings See proxy options above.
Local CVS Settings
Option Description Path to the CVS Client Specify the path to the local CVS client. Server Command Type the server command. The server command is the command which makes the CVS client to work in server mode. Default value is 'server'
Advanced Options
Option Description Use GZIP compression Check this option to apply gzip compression to the data passed between CVS server and CVS client. Send all environment variables to the CVS server Check this option to send environment variables to the server for the sake of compatibility with certain servers. History Command Supported Check this option to use the history file on server to search for newly committed changes. Enable this option to improve CVS support performance. By default, the option is checked off because not every CVS server supports keeping a history log file. Changes Checking Interval
Option Description Checking interval Select a radio button to choose between the global server setting of 60 seconds and entering a custom interval. Some public servers block access if polled frequently. VCS Root Sharing
Option Description
Document generated by Confluence on Jun 16, 2008 13:43 Page 187 VCS Root Sharing Enable this option to use this VCS root in other projects or build configurations. See Shared VCS Roots for more information.
See also:
• Concepts: Version Control System | VCS Root • Administrator's Reference: Configuring VCS Settings • UI Reference: Version Control Settings | New Edit VCS Roots
Document generated by Confluence on Jun 16, 2008 13:43 Page 188 New Edit VCS Roots
This page last changed on Mar 31, 2008 by serganch. New or Edit VCS Roots
Administration -> Create build configuration -> VCS Settings -> Create and attach new VCS root Administration -> Configure VCS roots -> edit -> edit or Create and attach new VCS root VCS Root Name
Option Description VCS root name Enter a unique name that distinguishes this VCS root from the others. If you don't enter one, it will be generated for you.
Type of Version Control System
Option Description Type of VCS Select a Version Control System from the drop-down list. The links below contain VCS-specific descriptions of the options you can specify when setting up VCS roots. TeamCity supports the following version control systems:
• ClearCase • CVS • Perforce • StarTeam • Subversion • Team Foundation Server • Visual SourceSafe
Note TeamCity needs to have the time synchronized between the VCS server and the machines that check out the project sources (server or agents, depending on the value of the build configuration's VCS checkout mode setting. This requirement applies to CVS, Subversion, and ClearCase configurations, as well as StarTeam if the audit is disabled or the server is older than 9.0. Upon completion of the VCS-specific settings you will be redirected back to the Version Control Settings page.
See also:
• Concepts: Version Control System | VCS Root • Administrator's Reference: Configuring VCS Settings
Document generated by Confluence on Jun 16, 2008 13:43 Page 189 Perforce
This page last changed on Jun 03, 2008 by ivrina. Perforce
This page contains descriptions of the fields and options available when setting up VCS roots using Perforce. P4 Connection Settings
Option Description Port Specify the Perforce server address. The format is host:port. Client Click this radio button to directly specify the client workspace. The workspace should already be created by Perforce client applications like P4V or P4Win. Only mapping rules are used from the configured client workspace. The client name is ignored. Client Mapping Click this radio button to specify the mapping of the depot to the client computer. Tip Use team-city-agent instead of the client name in the mapping. Example:
User Specify the user login name. Password Specify the password. Charset Select the character set used on the client computer. Ticket-based authentication Check this option to enable ticket-based authentication. Path to Perforce Command-Line Client Specify the path to the Perforce Command-Line Client (usually, p4.exe file ). Changes Checking Interval
Option Description Checking interval Select a radio button to choose between the global server setting of 60 seconds and entering a custom interval. Some public servers block access if polled frequently. VCS Root Sharing
Option Description VCS Root Sharing Enable this option to use this VCS root in other projects or build configurations. See Shared VCS Roots for more information.
Document generated by Confluence on Jun 16, 2008 13:43 Page 190 See also:
• Concepts: Version Control System | VCS Root • Administrator's Reference: Configuring VCS Settings • UI Reference: Version Control Settings | New Edit VCS Roots
Document generated by Confluence on Jun 16, 2008 13:43 Page 191 StarTeam
This page last changed on Mar 31, 2008 by serganch. StarTeam
This page describes the fields and options available when setting up VCS roots using StarTeam. StarTeam Connection Settings
Option Description URL Specify the StarTeam URL that points to the required sources Username Enter the login for the StarTeam Server Password Enter the corresponding password for the user specified in the field above EOL Conversion Define the EOL (End Of Line) symbol conversion rules for text files. Select one of the following:
• As stored in repository - EOL symbols are preserved as they are stored in the repository. No conversion is done. • Agent's platform default - Whatever EOL symbol is used in a particular file in the repository, it will be converted to the platform- specific line separator when passed to the build agent. The resulting EOL symbol exclusively depends on the agent's platform. Directory naming Please note that these options is available since TeamCity 3.1.1 Define the mode for naming the local directories. Select one of the following:
• Using working folders - StarTeam folders have the "working folder" property. It defines which local path corresponds to the StarTeam folder (by default, the working folder equals the folder's name). In this mode TeamCity gives the local directories the names stored in the "working folder" properties. Please note that even though StarTeam allows using absolute paths as working folders, TeamCity supports relative paths only and doesn't detect the presence of absolute paths. • Using StarTeam folder names - In this mode the local directories are named after corresponding StarTeam folders' names. This mode can suit users who keep the working directory structure the same as the project structure in the repository and don't want to rely on "working folder" properties because they can be uncontrollably modified. Checkout mode Files can be retrieved by their current (tip) revision, by label, or by promotion state. Note that if you select checkout by label or promotion state, change detection won't be possible for this VCS root. As a result, your builds cannot be triggered if the label is moved or the promotion state is switched to another label. The only way of keeping the build up-to-date is using the schedule- based triggering. To make it possible, a full checkout
Document generated by Confluence on Jun 16, 2008 13:43 Page 192 is always performed when you select checkout by label or promotion state options.
Notes on Directory Naming Convention
When checking out sources TeamCity (just as StarTeam native client) forms local directory structure using working folder names instead of just a folder name. By default, the working folder name for a particular StarTeam folder equals the folder's name. For example, your project has a folder named "A" with a subfolder named "B". By default, their working folders are "A" and "B" correspondingly, and the local directory structure will look like / A/B. But if the working folder for folder "A" is set to something different (for example, "Foo"), the directory structure will also be different: /Foo/B.
StarTeam allows specifying absolute paths as working folders. However, TeamCity supports only relative working folders. This is done by design; all files retrieved from the source control must reside under the checkout directory. The build will fail if TeamCity detects the presence of absolute working folders.
You need to ensure that all the folders under the VCS root have relative working folder names. Changes Checking Interval
Option Description Checking interval Select a radio button to choose between the global server setting of 60 seconds and entering a custom interval. Some public servers block access if polled frequently. VCS Root Sharing
Option Description VCS Root Sharing Enable this option to use this VCS root in other projects or build configurations. See Shared VCS Roots for more information.
See also:
• Concepts: Version Control System | VCS Root • Administrator's Reference: Configuring VCS Settings • UI Reference: Version Control Settings | New Edit VCS Roots
Document generated by Confluence on Jun 16, 2008 13:43 Page 193 Subversion
This page last changed on Apr 01, 2008 by ivrina. Subversion
This page contains descriptions of the fields and options available when setting up VCS roots using Subversion.
SVN Connection Settings
Option Description URL Specify the SVN URL that points to the project sources. User Name Specify the SVN user name. Password Specify the SVN password. Default Config Directory Check this option to make this the default configuration directory for the SVN connection. Configuration Directory If the Default Config Directory option is checked, you must specify the configuration directory. Externals Support Check one of the following options to control the SVN externals processing Checkout externals and load external changes If selected, TeamCity will check out all configuration's sources (including sources from the externals) and will gather and display information about externals' changes in the Changes tab. Ignore external changes If selected, TeamCity will check out the sources from externals but any changes in externals' source files will not be gathered and displayed in the Changes tab. You might use this option if you have several SVN externals and do not want to get information about any changes made in the externals' source files. Ignore externals If selected, TeamCity will ignore any configured 'svn:externals' property, and thus TeamCity will not check for changes or check out any source file from the SVN externals.
SSH Settings
Option Description Private Key File Path Specify the full path to the file that contains the SSH private key. Private Key File Password Enter the password to the SSH private key. SSH Port Specify the port that SSH is using.
Labeling settings
Option Description Labeling rules Specify a newline-delimited set of rules that defines the structure of the repository. See the detailed format description for more details.
Document generated by Confluence on Jun 16, 2008 13:43 Page 194 Changes Checking Interval
Option Description Checking interval Select a radio button to choose between the global server setting of 60 seconds and entering a custom interval. Some public servers block access if polled frequently. VCS Root Sharing
Option Description VCS Root Sharing Enable this option to use this VCS root in other projects or build configurations. See Shared VCS Roots for more information.
See also:
• Concepts: Version Control System | VCS Root • Administrator's Reference: Configuring VCS Settings • UI Reference: Version Control Settings | New Edit VCS Roots
Document generated by Confluence on Jun 16, 2008 13:43 Page 195 Team Foundation Server
This page last changed on Apr 25, 2008 by ivrina.
Team Foundation Server
This page contains descriptions of the fields and options available when setting up a VCS root using Team Foundation Server.
Option Description Team Foundation Server Specify the name of the computer in the company's network. Port Specify the port number. The default value is "8080". Protocol Select the protocol type to be used. The possible options are HTTP and HTTPS. User Name Specify the name of the user on the Team Foundation Server. This can be a domain name or a name of the user where the Team Foundation Server is installed. Password Enter the password of the user entered above. Root Specify the root using the following format:
$
Changes Checking Interval
Option Description Checking interval Select a radio button to choose between the global server setting of 60 seconds and entering a custom interval. Some public servers block access if polled frequently. VCS Root Sharing
Option Description VCS Root Sharing Enable this option to use this VCS root in other projects or build configurations. See Shared VCS Roots for more information.
See also:
• Concepts: Version Control System | VCS Root • Administrator's Reference: Configuring VCS Settings • UI Reference: Version Control Settings | New Edit VCS Roots
Document generated by Confluence on Jun 16, 2008 13:43 Page 196 Visual Source Safe
This page last changed on Apr 25, 2008 by ivrina. Visual Source Safe
This page contains descriptions of the fields and options available when setting up VCS roots using Visual SourceSafe.
Notes and Limitations
• Microsoft Visual SourceSafe only works if the TeamCity server is installed on a computer running a Windows® operating system. • Make sure the TeamCity server process is run by a user that has permission to access the VSS databases.
TeamCity has the following limitations with Visual SourceSafe:
• Shared (not branched) files cannot be checked out. • Comments for add and delete operations for file and directories are not shown in VSS 6.0. All such operations will have "No Comment" instead of a real VSS comment. (This limitation is imposed by the VSS API, which makes it impossible to retrieve comments with acceptable performance). VSS Settings
Option Description Path to srcsafe.ini The full path of the VSS configuration file srcsafe.ini of the project repository. If the TeamCity server is run as a Windows service, make sure this path does not use mapped drives. If the file is placed on a network drive use syntax like \ \vss-server\share\srcsafe.ini where vss-server is a server name and share is a name of the shared directory. Project Specify the mandatory path to the project tree, starting with $/. User Name Specify the mandatory name of the user on Visual SourceSafe server. Password Enter the password, that corresponds to the user name.
Changes Checking Interval
Option Description Checking interval Select a radio button to choose between the global server setting of 60 seconds and entering a custom interval. Some public servers block access if polled frequently. VCS Root Sharing
Option Description VCS Root Sharing Enable this option to use this VCS root in other projects or build configurations. See Shared VCS Roots for more information.
Document generated by Confluence on Jun 16, 2008 13:43 Page 197 See also:
• Concepts: Version Control System | VCS Root • Administrator's Reference: Configuring VCS Settings • UI Reference: Version Control Settings | New Edit VCS Roots
Document generated by Confluence on Jun 16, 2008 13:43 Page 198 3.Build Runners
This page last changed on May 20, 2008 by ivrina. Build Runners
Administration > > Runner
This section provides descriptions of the following build runners supported by TeamCity:
• Ant • Maven2 • NAnt • MSBuild • sln2003 — Microsoft Visual Studio 2003 solutions • sln2005 — Microsoft Visual Studio 2005 solutions • sln2008 — Microsoft Visual Studio 2008 solutions • Ipr — IntelliJ IDEA projects • Inspections — a set of IntelliJ IDEA inspections • Duplicates Finder (Java) • Duplicates Finder (.NET) • Simple Command Runner — run arbitrary command line
See also:
• Concepts: Build Runner • Administrator Reference: .NET Testing Frameworks Support | System Properties of a Build Configuration
Document generated by Confluence on Jun 16, 2008 13:43 Page 199 Ant
This page last changed on Feb 19, 2008 by chamilton. Ant
This page contains reference information about the Ant Build Runner fields.
Option Description Build runner Select Ant from the drop-down list. Artifact Paths Use this field to specify directories containing artifacts or file names as a comma-separated string. If a directory is specified its contents will be uploaded to the server. In version 3.1 this field is located on the General Settings page. Ant Parameters
Option Description Path to build.xml file If you choose this radio button, the text field is enabled, where you can type the path to the build.xml file of the project. The path is relative to the project root directory. Build file content If you choose this radio button, click the link Type build file content, and enter source code of your custom build file in the text area. Use Hide link to close the text area. Note that the text area is resizeable. Targets Use this text field to specify valid Ant targets as a list of space-separated strings. If this field is left empty, default target specified in build.xml file will be run. Ant home path Use this optional parameter to specify path to the distributive of your custom Ant. You do not need to specify this parameter, if you are going to use Ant distributive that comes bundled with TeamCity (Ant 1.7). Please note, that you should use Ant 1.7 if you want to run JUnit4 tests in your builds. Additional command line parameters Optionally, specify additional command line parameters as a space-separated list. Java Parameters
Option Description JDK home path Use this field to specify the path to your custom JDK which should be used to run the build. If the field is left blank, the path to JDK Home is read either from the JAVA_HOME environment variable on agent computer, or from env.JAVA_HOME property specified in the build agent configuration file (buildAgent.properties). If these both values are not specified, TeamCity uses Java home of the build agent process itself. If you have multiple build agents, it is recommended to specify value of this property
Document generated by Confluence on Jun 16, 2008 13:43 Page 200 as a reference to a property defined on specific build agent: %system.JDK_1_4%. After that you can specify the value of property system.JDK_1_4 in build agent's configuration file (buildAgent.properties) to the specific path to JDK 1.4 on this build agent:
system.JDK_1_4=/home/local/jdk_1.4.11
For all run parameters with values specified in terms of other properties (for example, %system.JAVA_1_4%), an implicit requirement is added (ensuring the referenced property is either defined on the agent machine or specified in the build parameters). JVM command line parameters You can specify such JVM command line parameters as, for example, maximum heap size or parameters enabling remote debugging. These values are passed by the JVM used to run your build. Example:
-Xmx512m -Xms256m
Build working directory Specify the build working directory.
Coverage Info
Option Description Code coverage Check this option, if you want code coverage to be analyzed. Note The mechanism used in TeamCity is based on EMMA open-source toolkit (see http:// emma.sourceforge.net/ for details). 'metadata is empty' problem For some complex build scripts, coverage metadata cannot be collected. In this case, try adding debug=true parameter to javac tasks in your ant script. If this option is not checked, the following two options are disabled. Include Source Files in the Coverage Data Check this option to include source files into the code coverage report (you'll be able to see sources on the Web). Warning Enabling this option can increase the report size and the slow down creation of your builds. To avoid this situation, you can specify some EMMA properties (see http:// emma.sourceforge.net/reference_single/ reference.html#prop-ref.tables for details). Coverage Instrumentation Parameters Use this field to specify the filters to be used for creating the code coverage report. These filters define classes to be exempted from instrumentation. For detailed description of filters refer to http:// emma.sourceforge.net/reference_single/ reference.html#prop-ref.tables.
Document generated by Confluence on Jun 16, 2008 13:43 Page 201 See also:
• System Administrator Reference: Ant
Document generated by Confluence on Jun 16, 2008 13:43 Page 202 Duplicates Finder (.NET)
This page last changed on Nov 30, 2007 by mio. Duplicates Finder (.NET)
This page contains reference information about the .NET Duplicates Finder Build Runner fields. The .NET Duplicates Finder Build Runner is intended for catching similar code fragments and providing a report on discovered repetitive blocks of C# and Visual Basic .NET code in Visual Studio 2003, 2005 and 2008 solutions.
TeamCity 3.0 supports C# up to version 2.0 and covers Visual Basic .NET up to version 8.0.
Option Description Build runner Select Duplicates Finder (.NET) from the drop- down list. Sources
Option Description Solution file path Enter the path, relative to the Project Root Directory, to the Visual Studio 2003, 2005 or 2008 solution file. Duplicate Searcher Settings
Option Description Fragments comparison Use these options to define which elements of the source code should be discarded when searching for repetitive code fragments. Code fragments can be considered duplicated, if they are structurally similar, but contain different variables, fields, methods, types or literals. Refer to the samples below: Normalize types to last subtype If this option is checked, similar contents with different namespace specifications will be recognized as duplicates.
Discard local variables If this option is checked, similar code fragments with different local variable names will be recognized as duplicates.
int a = 5; a += 6; int b = 5; b += 6;
Discard class fields name If this option is checked, the similar code fragments with different field names will be recognized as duplicates.
Document generated by Confluence on Jun 16, 2008 13:43 Page 203 Console.WriteLine(myFoo); Console.WriteLine(myBar); ... where myFoo and myBar are declared in the containing class
Discard types If this option is checked, similar content with different type names will be recognized as duplicates. That includes all possible type references (as shown below):
Logger.GetInstance("text"); OtherUtility.GetInstance("text"); ... where Logger and OtherUtility and both type names (thus GetInstance is a static method in both classes)
Logger a = (Logger) GetObject("object"); OtherUtility a = (OtherUtility) GetObject("object");
public int SomeMethod(string param); public void SomeMethod(object[] param);
Ignore duplicates with complexity simpler than Use this field to specify the lowest level of complexity of code blocks to be taken into consideration when detecting duplicates. Skip files by mask Enter files and wildcards to exclude files from the duplicates search (e.g. *_generated.cs). Skip files with opening comment Enter semicolon-separated keywords to exclude files that contain the keyword in a file's opening comments from the duplicates search. Skip regions by message substring Enter semicolon-separated keywords that exclude regions that contain the keyword in the message substring from the duplicates search. Entering "generated code", for example, will skip regions containing "Windows Form Designer generated code". Debug Check this option to include debug messages in the build log
Document generated by Confluence on Jun 16, 2008 13:43 Page 204 Duplicates Finder (Java)
This page last changed on Dec 03, 2007 by mio. Duplicates Finder (Java)
This page contains reference information about the Java Duplicates Finder Build Runner fields. The Java Duplicates Finder Build Runner is intended for catching similar code fragments and providing a report on discovered repetitive blocks of Java code. The Java Duplicates Finder is based on IntelliJ IDEA capabilities, thus an IntelliJ IDEA project file (.ipr) file is necessary to configure the runner. The Duplicates Finder can also find Java duplicates in projects being built by Maven2.
Option Description Build runner Select Duplicates Finder (Java) from the drop- down list. This runner is used for gathering IntelliJ IDEA duplicates results. IntelliJ IDEA Project Settings
Option Description Project file type Select a radio button to choose the type of the project (IntelliJ IDEA or Maven2). Path to the project file Use this field to specify the path to the project file (.ipr or pom.xml). This build runner requires this file to understand the structure of the project. Specified path can be relative to the project root directory or absolute. If the path is absolute, the project file should be accessible under this path on the server and on each of the build agents. Detect global libraries and module-based JDK in If this option is checked, the form all of the module *.iml files files will be automatically scanned for references to the global libraries and module JDKs when saved. This helps you ensure all references will be properly resolved. Warning When this opinion is selected, the process of opening and saving the build runner becomes settings may become time-consuming, because it involves loading and parsing all project module files. Unresolved Project Modules and Path Variables
This section displays messages when an IntelliJ IDEA module file (.iml) referenced from IPR file cannot be found as well as allows you to enter the values of path variables used in the IPR file. You may want to click the Save button to refresh values in this section.
Option Description This field appears, if the project file contains path macros, defined in the Path Variables dialog of IntelliJ IDEA's Settings dialog. In the Set value to field, specify a path to project resources, to be used on different build agents.
Document generated by Confluence on Jun 16, 2008 13:43 Page 205 Project JDKs
This section provides the list of JDKs detected in the project file.
Option Description JDK Home Use this field to specify JDK home for the project. When building with the Ipr runner, this JDK will be used to compile the sources of corresponding IDEA modules. For Inspections and Duplicate Finder builds, this JDK will be used internally to resolve the Java API used in your project. To run the build process itself the JDK specified in the JAVA_HOME environment variable will be used. JDK jar file patterns Click this link to open a text area, where you can define templates for the jar files of the project JDK. Use Ant rules to define the jar file patterns. The default value is used for Linux and Windows operating systems:
jre/lib/*.jar
For Mac OS X, use the following lines:
lib/*.jar
../Classes/*.jar
IDEA Home If your project uses the IDEA JDK, specify the location of IDEA's home directory IDEA Jar Files Patterns Click this link to open a text area, where you can define templates for the jar files of the IDEA JDK. You can use references to external properties when defining the values, like %system.idea_home % or %env.JDK_1_3%. This will add a requirement for the corresponding property. Project Global Libraries
This section appears if your project has references to global libraries (option Detect global libraries and module-based JDK in *.iml files should be enabled).
Option Description Path to Library Use this field to specify root directory which contains library jar files. Library Jar Files Patterns Click this link to open a text area, where you can define templates for the jar files of the library (default *.jar) You can use references to external properties when defining the values, like %env.CATALINA_BASE%. This will add a requirement for the corresponding property. JVM Settings
Option Description JVM command line parameters Specify the desired Java Virtual Machine parameters, such as maximum heap size or parameters that enable remote debugging. These settings are passed to the JVM used to run your build. Example:
Document generated by Confluence on Jun 16, 2008 13:43 Page 206 -Xmx512m -Xms256m
Additional Pre-Processing (Ant)
Option Description Run before build In the appropriate fields, enter the Ant scripts and targets (optional) that you want to run prior to starting the build.
Duplicate Finder Settings
Option Description Test sources If this option is checked, the test sources will be included in the duplicates analysis. Note
Tests contain the test data which can be duplicated. Thus, it does not make much sense to verify tests for duplicates. We recommend you not to select this option to avoid too long builds creation. Detalization level Use these options to define which elements of the source code should be distinguished when searching for repetitive code fragments. Code fragments can be considered duplicated, if they are structurally similar, but contain different variables, fields, methods, types or literals. Refer to the samples below: Distinguish Variables If this option is checked, the similar contents with different variable names will be recognized as different. If this option is not checked, such contents will be recognized as duplicated:
public static void main(String[] args) { int i = 0; int j = 0; if (i == j) { System.out.println("sum of " + i + " and " + j + " = " + i + j); }
long k = 0; long n = 0; if (k == n) { System.out.println("sum of " + k + " and " + n + " = " + k + n); } }
Distinguish Fields If this option is checked, the similar contents with different field names will be recognized as different. If this option is not checked, such contents will be recognized as duplicated:
Document generated by Confluence on Jun 16, 2008 13:43 Page 207 public void widgetDefaultSelected(SelectionEvent e) { } /*.....**/
});
myTree.addSelectionListener(new SelectionListener() { public void widgetDefaultSelected(SelectionEvent e) { } /*.....**/
});
Distinguish Methods If this option is checked, the methods of similar structure will be recognized as different. If this option is not checked, such methods will be recognized as duplicated. In this case, they can be extracted and reused. Initial version:
public void buildCanceled(Build build, SessionData data) { /* ... **/ for (IListener listener : getListeners()) { listener.buildCanceled(build, data); } }
public void buildFinished(Build build, SessionData data) { /* ... **/ for (IListener listener : getListeners()) { listener.buildFinished(build, data); } }
After duplicates analysis without distinguishing methods, the duplicated fragments can be extracted:
public void buildCanceled(final Build build, final SessionData data) { enumerateListeners(new Processor() { public void process(final IListener listener) { listener.buildCanceled(build, data); } }); }
public void buildFinished(final Build build, final SessionData data) { enumerateListeners(new Processor() { public void process(final IListener listener) { listener.buildFinished(build, data); } }); }
Document generated by Confluence on Jun 16, 2008 13:43 Page 208 private void enumerateListeners(Processor processor) {/* ... **/
for (IListener listener : getListeners()) { processor.process(listener); } }
Distinguish Types If this option is checked, the similar code fragments with different type names will be recognized as different. If this option is not checked, such code fragments will be recognized as duplicates.
new MyIDE().updateStatus()
new TheirIDE().updateStatus()
Distinguish Literals If this option is checked, similar line of code with different litarels will be considered different If this option is not checked, such lines will be recognized as duplicates.
myWatchedLabel.setToolTipText("Not Logged In");
myWatchedLabel.setToolTipText("Logging In...");
Ignore Duplicates with Complexity Simpler Than Complexity of the source code is defined by the amount of statements, expressions, declarations and method calls. Complexity of each of them is defined by its cost. Summarized costs of all these elements of the source code fragment yields the total complexity. Use this field to specify the lowest level of complexity of the source code to be taken into consideration when detecting duplicates. For meaningful results start with value 10. Ignore Duplicate Subexpressions with Complexity Use this field to specify the lowest level of Simpler Than complexity of subexpressions to be taken into consideration when detecting duplicates. Check if Subexpression Can be Extracted If this option is checked, the duplicated subexpressions can be extracted. If you need to restrict the sources scope on which to run the Duplicates runner, you can specify additional JVM parameters (in the JVM command line parameters field).
• all patters must end with either ** or * • includes have precedence over excludes • references to modules can be included as [module_name]/
Document generated by Confluence on Jun 16, 2008 13:43 Page 209 Inspections
This page last changed on Feb 08, 2008 by chamilton. Inspections
This page contains reference information about the Inspections Build Runner fields. This runner is intended for gathering inspection results in the IntelliJ IDEA or Maven2 projects.
Option Description Build runner Select Inspections from the drop-down list. This runner is used for gathering IntelliJ IDEA inspections results. IntelliJ IDEA Project Settings
Option Description Project file type Select a radio button to choose the type of the project (IntelliJ IDEA or Maven2). Path to the project file Use this field to specify the path to the project file (.ipr or pom.xml). This build runner requires this file to understand the structure of the project. Specified path can be relative to the project root directory or absolute. If the path is absolute, the project file should be accessible under this path on the server and on each of the build agents. Detect global libraries and module-based JDK in If this option is checked, the form all of the module *.iml files files will be automatically scanned for references to the global libraries and module JDKs when saved. This helps you ensure all references will be properly resolved. Warning When this opinion is selected, the process of opening and saving the build runner becomes settings may become time-consuming, because it involves loading and parsing all project module files. Unresolved Project Modules and Path Variables
This section displays messages when an IntelliJ IDEA module file (.iml) referenced from IPR file cannot be found as well as allows you to enter the values of path variables used in the IPR file. You may want to click the Save button to refresh values in this section.
Option Description This field appears, if the project file contains path macros, defined in the Path Variables dialog of IntelliJ IDEA's Settings dialog. In the Set value to field, specify a path to project resources, to be used on different build agents.
Project JDKs
This section provides the list of JDKs detected in the project file.
Document generated by Confluence on Jun 16, 2008 13:43 Page 210 Option Description JDK Home Use this field to specify JDK home for the project. When building with the Ipr runner, this JDK will be used to compile the sources of corresponding IDEA modules. For Inspections and Duplicate Finder builds, this JDK will be used internally to resolve the Java API used in your project. To run the build process itself the JDK specified in the JAVA_HOME environment variable will be used. JDK jar file patterns Click this link to open a text area, where you can define templates for the jar files of the project JDK. Use Ant rules to define the jar file patterns. The default value is used for Linux and Windows operating systems:
jre/lib/*.jar
For Mac OS X, use the following lines:
lib/*.jar
../Classes/*.jar
IDEA Home If your project uses the IDEA JDK, specify the location of IDEA's home directory IDEA Jar Files Patterns Click this link to open a text area, where you can define templates for the jar files of the IDEA JDK. You can use references to external properties when defining the values, like %system.idea_home % or %env.JDK_1_3%. This will add a requirement for the corresponding property. Project Global Libraries
This section appears if your project has references to global libraries (option Detect global libraries and module-based JDK in *.iml files should be enabled).
Option Description Path to Library Use this field to specify root directory which contains library jar files. Library Jar Files Patterns Click this link to open a text area, where you can define templates for the jar files of the library (default *.jar) You can use references to external properties when defining the values, like %env.CATALINA_BASE%. This will add a requirement for the corresponding property. JVM Settings
Option Description JVM command line parameters Specify the desired Java Virtual Machine parameters, such as maximum heap size or parameters that enable remote debugging. These settings are passed to the JVM used to run your build. Example:
-Xmx512m -Xms256m
Document generated by Confluence on Jun 16, 2008 13:43 Page 211 Additional Pre Processing (Ant)
Option Description Run before build In the appropriate fields, enter the Ant scripts and targets (optional) that you want to run prior to starting the build. The path to the Ant file should be relative to the project root directory. Inspections Parameters
Option Description Inspections profile path Use this text field to specify the path to inspections profiles file relative to the project root directory. By default, the profile path is specified in the IntelliJ IDEA project file *.ipr, and the field is left blank. Use this field, if you want to override project profile mapping. Inspections profile name Select the name of the desired shared profile from the combo box. By default, the name is unspecified, which means that project modules will be inspected according to their own settings. Errors limit Fail build if specified number of errors exceeded. By default first error that occurs will fail the build. Warnings limit Fail build if specified number of warnings exceeded. Leave blank if there is no limit. If you need to restrict the sources scope on which to tun the Inspections runner, you can specify additional JVM paramenters (in the JVM command line parameters field).
• all patters must end with either ** or * (this effectively limits the patterns to only the directories level, they do not support file-level patterns) • includes have precedence over excludes • references to modules can be included as [module_name]/ • "include" pattern has a special behaviour (due to underlying limitations): it includes the directory specified and all the files residing directly in the directories above the one specified. (in the example above, testData/basicTest.xml file will be included into the analysis)
Document generated by Confluence on Jun 16, 2008 13:43 Page 212 Ipr
This page last changed on Feb 28, 2008 by pavel.sher. IPR
This page contains reference information about the IPR Build Runner fields.
Option Description Build runner Select Ipr from the drop-down list. This runner generates a JUnit task for the tests in the project. Artifact Paths Use this field to specify directories containing artifacts or file names as a comma-separated string. If a directory is specified its contents will be uploaded to the server. In version 3.1 this field is located on the General Settings page. IntelliJ IDEA Project Settings
Option Description Path to the project file Use this field to specify the path to the project file (.ipr). This build runner requires this file to understand the structure of the project. Specified path should be relative to the project root directory Detect global libraries and module-based JDK in If this option is checked, the form all of the module *.iml files files will be automatically scanned for references to the global libraries and module JDKs when saved. This helps you ensure all references will be properly resolved. Warning When this option is selected, the process of opening and saving the build runner settings may become time-consuming, because it involves loading and parsing all project module files. Build working directory Enter a building working directory is your CVS checkout mode is set to Do not checkout files automatically. Unresolved Project Modules and Path Variables
This section displays messages when an IntelliJ IDEA module file (.iml) referenced from IPR file cannot be found as well as allows you to enter the values of path variables used in the IPR file. You may want to click the Save button to refresh values in this section.
Option Description This field appears, if the project file contains path macros, defined in the Path Variables dialog of IntelliJ IDEA's Settings dialog. In the Set value to field, specify a path to project resources, to be used on different build agents.
Document generated by Confluence on Jun 16, 2008 13:43 Page 213 Project JDKs
This section provides the list of JDKs detected in the project file.
Option Description JDK Home Use this field to specify JDK home for the project. When building with the Ipr runner, this JDK will be used to compile the sources of corresponding IDEA modules. For Inspections and Duplicate Finder builds, this JDK will be used internally to resolve the Java API used in your project. To run the build process itself the JDK specified in the JAVA_HOME environment variable will be used. JDK jar file patterns Click this link to open a text area, where you can define templates for the jar files of the project JDK. Use Ant rules to define the jar file patterns. The default value is used for Linux and Windows operating systems:
jre/lib/*.jar
For Mac OS X, use the following lines:
lib/*.jar
../Classes/*.jar
IDEA Home If your project uses the IDEA JDK, specify the location of IDEA's home directory IDEA Jar Files Patterns Click this link to open a text area, where you can define templates for the jar files of the IDEA JDK. You can use references to external properties when defining the values, like %system.idea_home % or %env.JDK_1_3%. This will add a requirement for the corresponding property. Project Global Libraries
This section appears if your project has references to global libraries (option Detect global libraries and module-based JDK in *.iml files should be enabled).
Option Description Path to Library Use this field to specify root directory which contains library jar files. Library Jar Files Patterns Click this link to open a text area, where you can define templates for the jar files of the library (default *.jar) You can use references to external properties when defining the values, like %env.CATALINA_BASE%. This will add a requirement for the corresponding property. JVM Settings
Option Description JVM command line parameters Specify the desired Java Virtual Machine parameters, such as maximum heap size or parameters that enable remote debugging. These settings are passed to the JVM used to run your build. Example:
Document generated by Confluence on Jun 16, 2008 13:43 Page 214 -Xmx512m -Xms256m
Additional Pre/Post Processing (Ant)
Option Description Run before build In the appropriate fields, enter the Ant scripts and targets (optional) that you want to run prior to starting the build. The path to the Ant file should be relative to the project root directory. Run after build In the appropriate fields, enter the Ant scripts and targets (optional) that you want to run after the build is completed. The path to the Ant file should be relative to the project root directory. JUnit Test Runner Settings
Note
JUnit test settings map to the attributes of JUnit task. For details, refer to http://ant.apache.org/ manual/OptionalTasks/junit.html Option Description Test patterns Click the Type test patterns link, and specify the required test patterns in a text area. These patterns are used to generate parameters of the batchtest JUnit task section. Each pattern generates either include or exclude section. These patterns are also used to compose classpath for the test run. Each module mentioned in the patterns adds its classpath to the whole classpath. Each pattern should be placed on a separate line and has the following format:
[-]moduleName:[testFileNamePattern]
where:
• [-]: If a pattern starts with minus character, the corresponding files will be excluded from the build process. • moduleName : this name can contain wildcards. • [testFileNamePattern] : Default value for testFileNamePattern is **/*Test.java , i.e. all files ending with Test.java in all directories. You can use Ant syntax for file patterns.The sample below includes all test files from modules ending with "test" and excludes all files from packages containing the "ui" subpackage:
*test:**/*Test.java -*:**/ui/**/*.java
Classpath in Tests By default the whole classpath is composed of all classpaths of the modules used to get tests from. The following two options define whether you
Document generated by Confluence on Jun 16, 2008 13:43 Page 215 will use the default classpath, or take it from the specified module. Override classpath in tests If this option is checked, you can define test classpath from a single, explicitly specified module. Module name to use JDK and classpath from If the option Override classpath in tests is checked, you have to specify the module, where the classpath to be used for tests is specified. JUnit Fork mode Select the desired fork mode from the combobox:
• Do not fork: fork is disabled. • Fork per test: fork is enabled, and each test class runs in a separate JVM • Fork once: fork is enabled, and all test classes run in a single JVM New classloader instance for each test Check this option, if you want a new classloader to be instantiated for each test case. This option is available only if Do not fork option is selected. Include Ant runtime Check this option to add Ant classes, required to run JUnit tests. This option is available if fork mode is enabled (Fork per test or Fork once). JVM executable Specify the command that will be used to invoke JVM. This option is available if fork mode is enabled (Fork per test or Fork once). Stop build on error Check this option, if you want the build to stop if an error occurs during test run. JVM command line parameters for JUnit Specify JVM parameters to be passed to JUnit task. Tests working directory Specify the path to the working directory for tests. Tests timeout Specify the lapse of time in milliseconds, after which test will be canceled. This value is ignored, if Do not fork option is selected. Verbose Ant Check this option, if the generated JUnit task has to produce verbose output in ant terms.
Coverage Info
Option Description Code coverage Check this option, if you want code coverage to be analyzed. Note The mechanism used in TeamCity is based on EMMA open-source toolkit (see http:// emma.sourceforge.net/ for details). 'metadata is empty' problem For some complex build scripts, coverage metadata cannot be collected. In this case, try adding debug=true parameter to javac tasks in your ant script. If this option is not checked, the following two options are disabled. Include Source Files in the Coverage Data Check this option to include source files into the code coverage report (you'll be able to see sources on the Web). Warning Enabling this option can increase the report size and the slow down creation of your builds. To avoid this situation, you can specify some EMMA properties (see http:// emma.sourceforge.net/reference_single/ reference.html#prop-ref.tables for details). Coverage Instrumentation Parameters Use this field to specify the filters to be used for creating the code coverage report. These filters
Document generated by Confluence on Jun 16, 2008 13:43 Page 216 define classes to be exempted from instrumentation. For detailed description of filters refer to http:// emma.sourceforge.net/reference_single/ reference.html#prop-ref.tables.
Document generated by Confluence on Jun 16, 2008 13:43 Page 217 Maven2
This page last changed on Feb 19, 2008 by chamilton. Maven2
This page contains reference information about the Maven2 Build Runner fields.
Option Description Build runner Select Maven2 from the drop-down list. Goals In the Goals field, you need to specify the sequence of Maven goals that you want TeamCity to execute. Some Maven goals can use version control systems, and, thus, they may become incompatible with some VCS checkout modes. If you want TeamCity to execute such goal:
• Select "Automatically on agent" for the VCS checkout mode on the Version Control Settings page. This makes the version control system available to a goal execution software. Path to a POM file Specify path to the POM file relative to the build working directory. By default, the property contains a pom.xml file. If you leave this field blank, the same value is put in this field. The path may also point to a subdirectory, and as such /pom.xml is used. Maven home path Use this optional parameter to specify path to the distributive of your custom Maven. You do not need to specify this parameter, if you are going to use the Maven distributive that comes bundled with TeamCity (Maven 2.0.8). Additional Maven command line parameters Specify the list of command line parameters. Note that -h, -v, -B, -s, -f are ignored. Artifact Paths Use this field to specify directories containing artifacts or file names as a comma-separated string. If a directory is specified its contents will be uploaded to the server. In version 3.1 this field is located on the General Settings page. User Settings Path The path to an alternative user settings file. It is equivalent to Maven's command line option -s or -- settings. JDK Home Path The path to JDK Home is read from the *JAVA_HOME* environment variable or *JDK home* specified on the build agent if you leave this field empty. If these two values are not specified as well, TeamCity uses the JDK home on which the build agent process is started. JVM Command Line Parameters Specify JVM command line parameters, for example, maximum heap size or parameters enabling remote debugging. These values are passed by the JVM used to run your build. Example:
-Xmx512m -Xms256m
Document generated by Confluence on Jun 16, 2008 13:43 Page 218 Build Working Directory Specify the build working directory. Note that the build working directory correlates with pom.xml file.
See also:
• System Administrator Reference: Maven2
Document generated by Confluence on Jun 16, 2008 13:43 Page 219 MSBuild
This page last changed on Feb 19, 2008 by chamilton. MSBuild
This page contains reference information for the MSBuild Build Runner fields.
Note Before setting up the build configuration to use MSBuild as the build runner, make sure you are using an XML build project file with the MSBuild runner. To build a Microsoft Visual Studio 2005 solution file please use the sln2005 runner. Option Description Build runner Select MSBuild from the drop-down list. Solution File Path Specify the path to the solution to be built, relative to the build working directory Example:
vs-addin\addin\addin.sln
Artifact Paths Use this field to specify directories containing artifacts or file names as a comma-separated string. If a directory is specified its contents will be uploaded to the server. In version 3.1 this field is located on the General Settings page. MSBuild version Use the drop-down list to select the version of .NET Framework you want to run. Build file validation Check this option to validate the build file. Targets Enter targets separated by spaces. A target is an arbitrary script for your project purposes. Command line parameters Specify any additional parameters for msbuild.exe Build Working Directory Specify the path to the build working directory.
See also:
• System Administrator Reference: Additional Functionality in MSBuild Scripts
Document generated by Confluence on Jun 16, 2008 13:43 Page 220 NAnt
This page last changed on Feb 19, 2008 by chamilton. NAnt
This page contains reference information about the NAnt Build Runner fields.
Option Description Build runner Select NAnt from the drop-down list. Artifact Paths Specify the artifacts as a comma-separated string. In version 3.1 this field is located on the General Settings page. Path to build file Specify path relative to the project root directory. Build File Content Click this radio-button, if you want to use a different build script than the one listed in the settings of the build file. If this option is selected, you have to type the build script in the text area. Targets Specify the names of build targets defined by the build script, separated by spaces. Build Working Directory If you want to specify the path to the build working directory, type the path in the text field. Command line parameters Specify any additional parameters for NAnt.exe.
See also:
• System Administrator Reference: NAnt
Document generated by Confluence on Jun 16, 2008 13:43 Page 221 Simple Command Runner
This page last changed on Feb 05, 2008 by chamilton. Simple Command Runner
With this build runner you can run any script supported by OS.
Option Description Build runner Select Command line from the drop-down list. Command executable Specify the executable file of the build runner. Command parameters Specify parameters as a space-separated list. Build working directory Specify the Build working directory, if you want to one other than the one already defined. Artifact Paths Use this field to specify directories containing artifacts or file names as a comma-separated string. If a directory is specified its contents will be uploaded to the server. In version 3.1 this field is located on the General Settings page.
Document generated by Confluence on Jun 16, 2008 13:43 Page 222 sln2003
This page last changed on Feb 20, 2008 by chamilton. sln2003
This page contains reference information for the sln2003 Build Runner for Microsoft Visual Studio 2003 projects.
Note
• The sln2003 build runner uses NAnt instead of MS Visual Studio 2003 to perform the build. As a result the agent is required to have .NET Framework 1.1 installed, however under certain conditions .NET Framework SDK 1.1 might be required. This NAnt solution task may behave differently than MS Visual Studio 2003. See http://nant.sourceforge.net/release/latest/help/ tasks/solution.html for details. • To use this runner you need to configure the NAnt runner. Please note that the page was restructured between versions 3.0 and 3.1. Please refer to the applicable description: 3.0 or 3.1. The sln 2003 Runner Page in Version 3.0
Option Description Build Runner Select sln2003 from the drop-down list. Solution File Path A path to the solution to be built is relative to the build working directory. Example:
vs-addin\addin\addin.sln
Configuration Specify the name of the solution configuration to build. Artifact Paths Specify the artifacts as a comma-separated string. Projects Output This group of options enables you to use the default output defined in the solution, or specify your own output path. Override project output Check this option to override output path settings specified in the solution / project. The overriding path should be entered in the field Output directory for all projects. If this option is not checked, all the build-related data will be uploaded to the bin/ directory. Output directory for all projects This option is available, if Override project output option is checked. Specify the directory where the compiled targets will be placed. Resolve URLs via Map Click this radio button, if you want to map the URL project path to the physical project path. If this option is selected, specify mapping in the Type the URL's map field. Type the URL's map Click this link and specify the desired map in the text area. Use the following format:
http://localhost:8111=myProjectPath/myProject
where http://localhost:8111 is a host where the project will be uploaded and myProjectPath/myProject is the project root
Document generated by Confluence on Jun 16, 2008 13:43 Page 223 Resolve URLs via WebDAV Click this radio button, if you want the URLs to be resolved via WebDav. Warning Make sure that all the necessary files are properly updated. The build agent may not update information from VCS implicitly. MS Visual Studio Reference Path Check this option, if you want to automatically include reference path of MS Visual Studio to the build. Run NUnit Tests for Specify .Net assemblies, where the NUnit tests to be run are stored. Multiple entries are comma- separated; usage of NAnt wildcards is enabled. In the following example, TeamCity will search for the tests assemblies in all project directories and run these tests.
**\*.dll
Note All these wildcards are specified relative to the project directory. Do not Run NUnit Tests for Specify .Net assemblies that should be excluded from the list of found assemblies to test. Multiple entries are comma-separated; usage of NAnt wildcards is enabled. In the following example, TeamCity will omit tests specified in this directory.
**\obj\**\*.dll
Note All these wildcards are specified relative to the project directory. Build Working Directory Specify the Build Working Directory.
The sln 2003 Runner Page in Version 3.1
Option Description Build Runner Select sln2003 from the drop-down list. Solution File Path A path to the solution to be built is relative to the Build Checkout Directory. Example:
vs-addin\addin\addin.sln
Working Directory Specify the Build Working Directory. Configuration Specify the name of the solution configuration to build. Projects Output This group of options enables you to use the default output defined in the solution, or specify your own output path. Output directory for all projects This option is available, if Override project output option is checked. Specify the directory where the compiled targets will be placed. Resolve URLs via Map Click this radio button, if you want to map the URL project path to the physical project path. If this option is selected, specify mapping in the Type the URL's map field.
Document generated by Confluence on Jun 16, 2008 13:43 Page 224 Type the URL's map Click this link and specify the desired map in the text area. Use the following format:
http://localhost:8111=myProjectPath/myProject
where http://localhost:8111 is a host where the project will be uploaded and myProjectPath/myProject is the project root Resolve URLs via WebDAV Click this radio button, if you want the URLs to be resolved via WebDav. Warning Make sure that all the necessary files are properly updated. The build agent may not update information from VCS implicitly. MS Visual Studio Reference Path Check this option, if you want to automatically include reference path of MS Visual Studio to the build. Run NUnit Tests for Specify .Net assemblies, where the NUnit tests to be run are stored. Multiple entries are comma- separated; usage of NAnt wildcards is enabled. In the following example, TeamCity will search for the tests assemblies in all project directories and run these tests.
**\*.dll
Note All these wildcards are specified relative to path that contains the solution file. Do not Run NUnit Tests for Specify .Net assemblies that should be excluded from the list of found assemblies to test. Multiple entries are comma-separated; usage of NAnt wildcards is enabled. In the following example, TeamCity will omit tests specified in this directory.
**\obj\**\*.dll
Note All these wildcards are specified relative to path that contains the solution file.
See also:
• System Administrator Reference: Additional Functionality in MSBuild Scripts
Document generated by Confluence on Jun 16, 2008 13:43 Page 225 sln2005
This page last changed on Feb 20, 2008 by chamilton. sln2005
This page contains reference information for sln2005 Build Runner that builds Microsoft Visual Studio 2005 solution files. Note that sln2005 works the same as sln2008 only it uses MSBuild from .NET version 2.0.
Please note that the page was restructured between versions 3.0 and 3.1. Please refer to the applicable description: 3.0 or 3.1. The sln 2005 Runner Page in Version 3.0
Option Description Build runner Select sln2005 from the drop-down list. Solution File Path Specify the path to the solution to be built relative to the Build Working Directory. Example:
vs-addin\addin\addin.sln
Artifact Paths Specify artifacts as a comma-separated string. Targets Specify the Microsoft Visual Studio 2005-specific targets. The possible options are Build, Rebuild, Clean, Publish or a combination of these targets based on your needs. Multiple targets are space- separated. Configuration Specify the name of the MS VS 2005 solution configuration to build. Platform Specify the platform for the solution. You can leave this field blank, and TeamCity obtains this information from the solution settings. Run NUnit/VSTS Unit tests for Specify the .Net assemblies, where the NUnit tests to be run are stored. Multiple entries are comma- separated; usage of MSBuild wildcards is enabled. In the following example, TeamCity will search for the tests assemblies in all project directories and run these tests.
**\*.dll
Note All these wildcards are specified relative to the project directory. Do not run NUnit/VSTS Unit tests for Specify .Net assemblies that should excluded from the list of found assemblies to test. Multiple entries are comma-separated; usage of MSBuild wildcards is enabled. In the following example, TeamCity will omit tests specified in this directory.
**\obj\**\*.dll
Note
Document generated by Confluence on Jun 16, 2008 13:43 Page 226 All these wildcards are specified relative to the project directory. Build Working Directory Specify the Build Working Directory.
The sln 2005 Runner Page in Version 3.1
Option Description Build runner Select sln2005 from the drop-down list. Solution File Path Specify the path to the solution to be built relative to the Build Checkout Directory. Example:
vs-addin\addin\addin.sln
Working Directory Specify the Build Working Directory. Targets Specify the Microsoft Visual Studio 2005-specific targets. The possible options are Build, Rebuild, Clean, Publish or a combination of these targets based on your needs. Multiple targets are space- separated. Configuration Specify the name of the MS VS 2005 solution configuration to build. Platform Specify the platform for the solution. You can leave this field blank, and TeamCity obtains this information from the solution settings. Run NUnit/VSTS Unit tests for Specify the .Net assemblies, where the NUnit tests to be run are stored. Multiple entries are comma- separated; usage of MSBuild wildcards is enabled. In the following example, TeamCity will search for the tests assemblies in all project directories and run these tests.
**\*.dll
Note All these wildcards are specified relative to path that contains the solution file. Do not run NUnit/VSTS Unit tests for Specify .Net assemblies that should excluded from the list of found assemblies to test. Multiple entries are comma-separated; usage of MSBuild wildcards is enabled. In the following example, TeamCity will omit tests specified in this directory.
**\obj\**\*.dll
Note All these wildcards are specified relative to path that contains the solution file.
See also:
• System Administrator Reference: Additional Functionality in MSBuild Scripts
Document generated by Confluence on Jun 16, 2008 13:43 Page 227 sln2008
This page last changed on Feb 20, 2008 by chamilton. sln2008
This page contains reference information for the sln2008 Build Runner that builds Microsoft Visual Studio 2008 solution files. Note that sln2008 works the same as sln2005 only it uses MSBuild from .NET version 3.5
Please note that the page was restructured between versions 3.0 and 3.1. Please refer to the applicable description: 3.0 or 3.1. The sln 2008 Runner Page in Version 3.0
Option Description Build runner Select sln2008 from the drop-down list. Solution File Path Specify the path to the solution to be built relative to the Build Working Directory. Example:
vs-addin\addin\addin.sln
Artifact Paths Specify artifacts as a comma-separated string. Targets Specify the Microsoft Visual Studio 2008-specific targets. The possible options are Build, Rebuild, Clean, Publish or a combination of these targets based on your needs. Multiple targets are space- separated. Configuration Specify the name of MS VS 2008 solution configuration to build. Platform Specify the platform for the solution. You can leave this field blank, and TeamCity obtains this information from the solution settings. Run NUnit/VSTS Unit tests for Specify the .Net assemblies, where the NUnit tests to be run are stored. Multiple entries are comma- separated; usage of MSBuild wildcards is enabled. In the following example, TeamCity will search for the tests assemblies in all project directories and run these tests.
**\*.dll
Note All these wildcards are specified relative to the project directory. Do not run NUnit/VSTS Unit tests for Specify .Net assemblies that should excluded from the list of found assemblies to test. Multiple entries are comma-separated; usage of MSBuild wildcards is enabled. In the following example, TeamCity will omit tests specified in this directory.
**\obj\**\*.dll
Note
Document generated by Confluence on Jun 16, 2008 13:43 Page 228 All these wildcards are specified relative to the project directory. Build Working Directory Specify the Build Working Directory.
The sln 2008 Runner Page in Version 3.1
Option Description Build runner Select sln2008 from the drop-down list. Solution File Path Specify the path to the solution to be built relative to the Build Checkout Directory. Example:
vs-addin\addin\addin.sln
Working Directory Specify the Build Working Directory. (optional) Targets Specify the Microsoft Visual Studio 2008-specific targets. The possible options are Build, Rebuild, Clean, Publish or a combination of these targets based on your needs. Multiple targets are space- separated. Configuration Specify the name of MS VS 2008 solution configuration to build. Platform Specify the platform for the solution. You can leave this field blank, and TeamCity obtains this information from the solution settings. Run NUnit/VSTS Unit tests for Specify the .Net assemblies, where the NUnit tests to be run are stored. Multiple entries are comma- separated; usage of MSBuild wildcards is enabled. In the following example, TeamCity will search for the tests assemblies in all project directories and run these tests.
**\*.dll
Note All these wildcards are specified relative to path that contains the solution file. Do not run NUnit/VSTS Unit tests for Specify .Net assemblies that should excluded from the list of found assemblies to test. Multiple entries are comma-separated; usage of MSBuild wildcards is enabled. In the following example, TeamCity will omit tests specified in this directory.
**\obj\**\*.dll
Note All these wildcards are specified relative to path that contains the solution file.
See also:
• System Administrator Reference: Additional Functionality in MSBuild Scripts
Document generated by Confluence on Jun 16, 2008 13:43 Page 229 4.Build Triggering
This page last changed on Dec 03, 2007 by mio. Build Triggering
Administration > project> > Build triggering
Option Description Pause/Activate Use this button to toggle the active and paused state of a build configuration. In the paused state, build configuration will not be triggered automatically, and you will need to click the Run button on the Projects tab to trigger the build.
Use this tab to create a list of build configurations which the current build configuration depends on. If such relationship exists, the build of dependent build configuration will start only after the successful completion of the dependency.
Option Description Add dependency on Click this link to show a list of existing projects and their build configurations, from which you can select the dependencies. Remove dependency Click this link to eliminate the selected dependency.
See also:
• Concepts: Build Trigger
Document generated by Confluence on Jun 16, 2008 13:43 Page 231 Other Triggers
This page last changed on Dec 27, 2007 by chamilton. Other Triggers
Administration > project> > Build triggering > Other Triggers
Option Description Automatically start a new build when the previous Check this option, to trigger a new build when the build failed last build failed Wait for [ ] seconds before starting a new build Specify the time delay in seconds. Save Click this button to preserve all changes.
See also:
• Concepts: Build Trigger
Document generated by Confluence on Jun 16, 2008 13:43 Page 232 Schedule
This page last changed on Jan 31, 2008 by chamilton. Schedule
Use this page to configure time-based triggering for your build configuration.
Option Description Add time trigger Click this link to open the Add trigger dialog. Add trigger dialog Trigger build Select build frequency from the drop-down list. Options include: daily, weekly, and advanced (cron expression). Time Select a start time for the build from the 24 hour drop-down list. Do not trigger build if there are no pending changes Check this option to skip builds, if TeamCity does not detect any changes in the VCS roots.
See also:
• Concepts: Build Trigger
Document generated by Confluence on Jun 16, 2008 13:43 Page 233 Cron Expression Build Trigger
This page last changed on Feb 18, 2008 by chamilton. Cron Expression Build Trigger
This feature is only available in TeamCity 3.1
Since TeamCity 3.1 builds can be scheduled using cron-like expressions. The format allows for maximum flexibility of scheduling options. Examples
Field Name Each 2 Every day Every Sunday Every last day of hours at :30 at 11:45PM at 1:00AM month at 10:00AM and 10:00PM Seconds 0 0 0 0 Minutes 30 45 0 0 Hours 0/2 23 1 10,22 Day-of-month * * ? L Month * * * * Day-of-week ? ? 1 ? Year(Optional) * * * *
See also other examples. Brief description of the cron format used
Cron expressions are comprised of six fields and one optional field separated with a white space. The fields are respectively described as follows:
Field Name Values Special Characters Seconds 0-59 , - * / Minutes 0-59 , - * / Hours 0-23 , - * / Day-of-month 1-31 , - * ? / L W Month 1-12 of JAN-DEC , - * / Day-of-week 1-7 or SUN-SAT , - * ? / L # Year(Optional) empty, 1970-2099 , - * /
The '' character is used to specify all values. For example, '' in the minute field means "every minute".
The '?' character is allowed for the day-of-month and day-of-week fields. It is used to specify 'no specific value'. This is useful when you need to specify something in one of the two fields, but not the other.
The '-' character is used to specify ranges For example "10-12" in the hour field means "at the top of hour, at 10, 11 and 12".
The ',' character is used to specify additional values. For example "MON,WED,FRI" in the day-of-week field means "the days Monday, Wednesday, and Friday".
The '/' character is used to specify increments. For example "0/15" in the seconds field means "the seconds 0, 15, 30, and 45". And "5/15" in the seconds field means "the seconds 5, 20, 35, and 50". Specifying '*' before the '/' is equivalent to specifying 0 is the value to start with. Essentially, for each field in the expression, there is a set of numbers that can be turned on or off. For seconds and minutes, the numbers range from 0 to 59. For hours 0 to 23, for days of the month 0 to 31, and for months 1 to 12. The "/" character simply helps you turn on every "Nth" value in the given set. Thus "7/6" in the month field only turns on month "7", it does NOT mean every 6th month, please note that subtlety.
Document generated by Confluence on Jun 16, 2008 13:43 Page 234 The 'L' character is allowed for the day-of-month and day-of-week fields. This character is short-hand for "last", but it has different meaning in each of the two fields. For example, the value "L" in the day- of-month field means "the last day of the month" - day 31 for January, day 28 for February on non-leap years. If used in the day-of-week field by itself, it simply means "7" or "SAT". But if used in the day- of-week field after another value, it means "the last xxx day of the month" - for example "6L" means "the last Friday of the month". When using the 'L' option, it is important not to specify lists, or ranges of values, as you'll get confusing results.
The 'W' character is allowed for the day-of-month field. This character is used to specify the weekday (Monday-Friday) nearest the given day. As an example, if you were to specify "15W" as the value for the day-of-month field, the meaning is: "the nearest weekday to the 15th of the month". So if the 15th is a Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. However if you specify "1W" as the value for day-of-month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not 'jump' over the boundary of a month's days. The 'W' character can only be specified when the day-of- month is a single day, not a range or list of days.
The 'L' and 'W' characters can also be combined for the day-of-month expression to yield 'LW', which translates to "last weekday of the month".
The '#' character is allowed for the day-of-week field. This character is used to specify "the Nth" XXX day of the month. For example, the value of "6#3" in the day-of-week field means the third Friday of the month (day 6 = Friday and "#3" = the third one of the month). Other examples: \
• "2#1" = the first Monday of the month and • "4#5" = the fifth Wednesday of the month. Note that if you specify • "#5" and the given day-of-week doesn't occur five times during that month, nothing will happen.
The legal characters and the names of months and days of the week are not case sensitive.
TeamCity uses Quartz for working with cron expressions.
See also:
Concepts: Build Trigger
Document generated by Confluence on Jun 16, 2008 13:43 Page 235 VCS Triggers
This page last changed on May 27, 2008 by yaegor. VCS Triggers
Option Description Enable triggering when updated files are checked Check this option if you want to trigger build, when into VCS pending changes appear in project. When this option is checked, TeamCity will check VCS for changes every 60 seconds and trigger the build if changes are found. The time between checks can be configured in on the Server Configuration page (Administration > Edit Server Configuration), or in the VCS root settings, or by modifying the Java system property modification.check.interval on the TeamCity Server as described in the System Properties for Running the Server section. Quiet period setting The length of time in seconds that must pass without any commits to the build configuration's VCS roots before Team City will start the build. Build trigger rules Use this text area to enter the rules that determine what VCS activity will automatically trigger builds. See Configuring Build Triggers for more information. Save Click this button to preserve your changes.
If the build configuration contains artifact dependencies, the following information is presented for each dependency:
Option Description Artifacts source The dependency in the following format:
::
Artifacts path The path to the artifact dependency on the server. Destination path The target location of the dependency on the build agent. Edit Click this link to modify the selected dependency. Delete Click this link to remove the selected dependency.
Add / Edit Dependency
Option Description Add new dependency Click this link to specify the artifact dependency. Depend on Specify the build configuration that the current build configuration should depend on. Get artifacts from Specify the type of build, from which the artifacts should be taken. The following options are available:
• Last successful build • Last pinned build • Last finished build • Build number Note When selecting the build configuration, take your clean-up policy settings into account. Builds are cleaned and deleted on a regular basis, thus the build configuration could become dependent on a non-existent build. When artifacts are taken from a build with a specific number, then the specific build will not be deleted during clean-up. Build number Use this field to specify the exact build number of the artifact. This field is enabled, if the Build number option is selected in the Get artifacts from field. Artifacts path Specify the artifact's path to the "source" build. The path should be relative to the artifacts directory of the "source" build. The path can either match a specific file, or wildcards (*, ?) can be used to include multiple files and directory names. Note the
Document generated by Confluence on Jun 16, 2008 13:43 Page 237 "." that separates the file name from the extension is not matched by either "*" or "?" and, if necessary, should be included in the wildcard directly. Please also note that downloaded artifacts will have the same directory structure as the source artifacts. For example: use a/b/*.* to download all files with extension from a/b directory of the source build. If there is a a/b/c/file.txt file in the source build artifacts, it will be donwloaded into the file: DestinationPath/a/b/c/file.txt More artifacts Click this link to open an additional text field, where you can specify the path to additional artifacts. Destination path Specify the destination path on the agent where downloaded artifacts should be placed. If the path is relative, it will be resolved against the build checkout directory. If needed, the destination path can be cleaned before downloading artifacts. Clean directory before downloading artifacts Check this option to delete the content of the destination directory before copying artifacts. Save Preserve changes and close the page.
Document generated by Confluence on Jun 16, 2008 13:43 Page 238 6.Properties and environment variables
This page last changed on May 07, 2008 by ivrina. Properties and environment variables
Administration > > Properties and environment variables
Refer to the System Properties of a Build Configuration section for properties description. System properties
Option Description Predefined system properties These read-only fields show the list of predefined properties. Edit Click this link to modify the system property in the Edit Property dialog. Delete Click this link to remove the selected property. Add new property Click this link to create new property as a name- value pair in the Add New Property dialog.
Environment variables
Option Description Predefined environment variables These read-only fields show the list of environment variables that will be passed to the bulid process. Edit Click this link to modify the environment variable in the Edit Vaiable dialog. Delete Click this link to remove the selected property. Add new variable Click this link to create new variable as a name- value pair in the Add New variable dialog. Add/Edit Property / Variable dialog
Option Description Name Use this text field to specify the name of the property or variable. Value Use this text field to specify the value of the property or variable. Save Click this button to preserve changes and close the dialog. Cancel Click this button to discard changes and close the dialog. Close Click this button to discard changes and close the dialog.
Document generated by Confluence on Jun 16, 2008 13:43 Page 239 7.Agent Requirements
This page last changed on Feb 06, 2008 by mio. Agent Requirements
Administration > Agent requirements
Use this page to specify the required system properties and environment variables that build agents must meet in order to be able to run the builds of the current build configuration.
Option Description Frequently used requirements Click this link to view a dialog with a list of frequently used requirements. You can select the desired requirements and add them to your list. Requirements for system properties
Option Description edit Click this link to change selected requirement in the Edit Requirement dialog. delete Click this link to delete selected requirement. Add requirement Click this link to create a new requirement for a property in the Add Requirement dialog. Requirements for environment variables
Option Description edit Click this link to change selected requirement in the Edit Requirement dialog. delete Click this link to delete selected requirement. Add requirement Click this link to create a new requirement for a property in the Add Requirement dialog.
Add / Edit Requirement dialog
Option Description Property or environment variable name Specify the mandatory property or environment variable name. Condition Select condition from the drop-down list. Some notes on how conditions work:
• equals: This condition will be true if an empty value is specified and the specified property exists and its value is an empty string; or if a value is specified and the property exists with the specified value. • does not equal: This condition is true if an empty value is specified and the property exists and its value is NOT empty; or if a specific value is specified and either the property doesn't exist, or the property exists and its value does not equal the specified value. • does not contain: This condition will be true if the specified property either does
Document generated by Confluence on Jun 16, 2008 13:43 Page 240 not exist or exists and does not contain the specified string. • is more than, is not more than, is less than, is not less than: These conditions only work with numbers. • (since TeamCity 2.1) matches, does not match: This condition will be true if specified property matches/does not match the specified Regular Expression pattern. Value Is shown for some conditions that require value, e.g. equals Save Preserve changes and close the dialog. Agents compatibility
This section shows the list of compatible and incompatible build agents for this build configuration. Possible reasons why build agent may be incompatible with this build configuration are described separately.
Document generated by Confluence on Jun 16, 2008 13:43 Page 241 Create Edit Project
This page last changed on Apr 25, 2008 by ivrina. Create / Edit Project
Open the Administration page and click Create project link or select a project and click Edit.
Option Description Name Use this mandatory text field to specify the project name. Description Use this text field to enter an optional description of the project. Create Click this button to create an empty project. This button is available when creating a new project. After clicking this button, you can proceed with creating build configurations, configuring your VCS settings, and build runners. Save Click this button to save changes you have done to the project being edited. This button is available when editing an existing project. Cancel Click this button to discard all changes and return to the Administration page. Copy Click this button to clone the selected project with its configuration. Build history and artifacts are not copied. Delete Click this button to delete the selected project with its build history, artifacts, etc. Build configurations Use this section to manage the project's build configurations. Click the configuration's name to open it for editing. Edit Click this link to edit the selected build configuration. Copy Click this link to clone the selected build configuration. In doing so the build counter resets to 1. Delete Click this link to delete the selected build configuration with its history, artifacts, changes etc. Physically, the deleted build configuration is preserved until the next clean-up, which gives you a chance to restore it, if necessary. Create build configuration Click this link to create a new build configuration from scratch. VCS roots used in this project Use this section to manage the VCS roots used by this project. Click on the VCS root's name to open it for editing. Edit Click this link to revise the VCS root. (see Configuring VCS Roots) The project's build configurations that use this VCS root appear in the Used in column of the table. Click the build configuration's name to edit its VCS settings or use the drop-down list see or navigate to build configurations from different projects that use this VSC root. Unused VCS roots Use this section to manage any VCS roots that no longer being used by of the project's build configurations. Click on the VCS root's name to open it for editing. Edit Click this link to revise the VCS root. (see Configuring VCS Roots)
Document generated by Confluence on Jun 16, 2008 13:43 Page 242 Delete Click this link to delete the selected VCS root.
Document generated by Confluence on Jun 16, 2008 13:43 Page 243 Licenses
This page last changed on Nov 29, 2007 by yaegor.
Licenses
Administration > Manage licenses
Item Description TeamCity is currently running in enterprise/ This field informs about the edition of TeamCity, professional mode defined by the license keys entered. Maximum number of licensed agents This field shows the number of bundled (free) agents, and the number of additional agents according to the entered agent license keys. Entered license keys This table displays the list of license keys, and provides a link enabling you to remove a license. Enter new license(s) Click this link to open a field for entering one or more license keys to switch to the Enterprise mode of add additional agents. Each license should be placed on a separate line.
Document generated by Confluence on Jun 16, 2008 13:43 Page 244 Server Configuration
This page last changed on Feb 05, 2008 by chamilton. Server Configuration
Administration > Edit Server Configuration
Please note that the page was restructured between versions 3.0 and 3.1. Please refer to the applicable description: 3.0 or 3.1. The Edit Server Configuration Page in Version 3.0
Option Description Authentication settings Current scheme This read-only section displays the name of the current authentication scheme. Refer to Authentication Settings to learn how to change the current scheme. Welcome text on the login page Use this field to view or edit the greeting that will be displayed in the login page. User name Use this field to specify login name of the user. This field is available, if the current authentication scheme is LDAP. Password Use this field to specify password of the user. This field is available, if the current authentication scheme is LDAP. Guest user login Check this option to allow logging in without a license. Save Click this button to apply your changes. Email notifier settings This section displays the current settings of the email notifier. Edit settings Click this link to open Edit Email Notifier Settings page. Jabber notifier settings This section displays the current settings of the Jabber notifier. Edit settings Click this link to open Edit Jabber Notifier Settings page.
The Edit Server Configuration Page in Version 3.1
Option Description General Settings TeamCity Configuration Data directory: A read-only field that displays the default directory where TeamCity will save data and settings information. Please refer to TeamCity Data Directory for additional information. Artifacts directory: A read-only field that displays the default directory for artifacts. Maximum artifact size: Enter a value to limit the maximum size of the artifacts. Enter -1 to not limit the size of the artifacts. Server URL: Enter the web address used for accessing the TeamCity server. Version Control Settings
Document generated by Confluence on Jun 16, 2008 13:43 Page 245 Default VCS changes check interval: Enter the amount of time in seconds that TeamCity will wait between polling the Version Control System(s) for changes. Default VCS trigger quiet period: Enter the amount of time in seconds that needs to pass without any commits to the build configuration's VCS roots before Team City will start the build. Authentication Scheme Current scheme: This read-only section displays the name of the current authentication scheme. Refer to Authentication Settings to learn how to change the current scheme. Welcome text on the login page: Use this field to view or edit the greeting that will be displayed in the login page. User name Use this field to specify login name of the user. This field is only available, if the current authentication scheme is LDAP. Password Use this field to specify password of the user. This field is only available, if the current authentication scheme is LDAP. Guest User Guest user login Check this option to give guest users access to the TeamCity server. Configure guest user roles This field is only available for Enterprise Edition users. Click this link to navigate to the Edit Roles of Guest User page and edit the access level that guests have. Guest user username: Enter a customized login name for guest users. Save Click this button to apply your changes. Notifier Settings Email notifier settings This section displays the current settings of the email notifier. Edit settings Click this link to open Edit Email Notifier Settings page. Jabber notifier settings This section displays the current settings of the Jabber notifier. Edit settings Click this link to open Edit Jabber Notifier Settings page.
See also:
• Email and Jabber Notifier Settings
Document generated by Confluence on Jun 16, 2008 13:43 Page 246 Email and Jabber Notifier Settings
This page last changed on Feb 15, 2008 by chamilton. Email Notifier Settings
Administration > Server Configuration > Edit Settings
Option Description SMTP host Specify the SMTP host name. SMTP port Specify the SMTP port number. Send messages from Specify the email address, from which notification messages will be sent to the user. SMTP login Specify the SMTP login name, if any. SMTP password Specify the SMTP password. Use TLS (SSL) Select this option to secure your SMTP connection with TLS. This feature is only available in TeamCity 3.1+ Test connection Click this button to establish a connection with the specified SMTP host. Save Click this button to save changes and close the page. Jabber Notifier Settings
Administration > Server Configuration > Edit Settings
Option Description Jabber server Specify the name of the Jabber server, through which TeamCity sends messages. Server port Specify the port number. Server user Specify the name of the Jabber user, from which TeamCity sends messages. Server password Specify the password to the Jabber server, where the user is registered. Test connection Click this button to establish a connection with the specified Jabber server. Save Click this button to save changes and close the page.
Document generated by Confluence on Jun 16, 2008 13:43 Page 247 User Accounts
This page last changed on Dec 26, 2007 by chamilton.
User Accounts
Administration > Configure user accounts
The content of this page depends on the authentication settings of the server configuration and TeamCity edition you have. For example, user accounts search and assigning roles are not available in TeamCity Professional.
Use this page to do the following:
• View the list of users registered in the system. • Configure default user roles and guest user roles. • Edit or delete user accounts. • Assign roles and permissions to the selected users. • Search for users (by their name, e-mail, role in the system, etc.) and filter the user accounts.
Option Description Add new user This link is only available for the default authentication scheme that allows adding new users. For NT and LDAP authentication schemes, the list of users coincides with the domain user database. Configure default user roles Click this link to configure the default user roles, which will be assigned by default to each newly created user. Use Assign role link to associate the default user account with a role for the selected projects. Configure guest user roles Click this link to assign roles and permissions of the guest user. When a new guest user account is created, it gets the specified roles by default. Use Assign role link to associate the default guest account with a role for the selected projects. Find Use this field to type the search string. This can be a user visible name, full name, or email address, or a part of it. Click the Filter button to apply this filter and show the list of users that match the specified string. Role Select the role assigned to the user. Click the Filter button to apply this filter and show the list of users with the specified role. Project Select the project the user has access to. Click the Filter button to apply this filter and show the list of users have access to the selected project. Filter Click this button to apply the specified filter (name, role and/or project) to narrow the list user accounts. Invert roles filter Check this option to invert the search result and show the list of users that do not have the specified role. Users to show Select the number of user accounts to display in one page. Assign roles to the selected users Click this link to assign a role to one or more selected users from the table below. Table of Users Each user entry in the table shows user login name, full name, email and last access time. Clicking on a column header, you can sort the table by each column in ascending or descending order. Clicking an entry opens Edit General Settings of the User page.
Document generated by Confluence on Jun 16, 2008 13:43 Page 248 See also:
Document generated by Confluence on Jun 16, 2008 13:43 Page 249 Assign Roles
This page last changed on Nov 26, 2007 by yaegor. Assign Roles Dialog
Administration > Configure user accounts > Assign roles to the selected users
Administration > Configure user accounts > Configure default user roles > Assign roles
Administration > Configure user accounts > Configure guest user roles > Assign roles
Use this dialog to configure the roles that will be assigned to a default user, guest user or a particular user, selected from the list.
Item Description Role Use this drop-down list to select a role, which will be assigned to the user in question. permissions View the list of permissions, associated with the selected role. Note that permissions are assigned per project. In projects Use this drop-down list to select a project, in which the permissions are granted. A user can have permissions for a specific project, or for all available projects. Replace existing roles with newly created Check this option to remove all existing roles from the list of roles for a particular user, and replace them with the selected role. If the option is not checked, the new role is added to the list. Assign Click this button to assign a role to the selected users for a certain project. Cancel / Close Discard all changes and close the dialog.
See also:
• Concepts: Account| Permission | Role • UI Reference: User Account
Document generated by Confluence on Jun 16, 2008 13:43 Page 250 Edit General Settings of the User
This page last changed on Feb 05, 2008 by chamilton. Edit General Settings of the User
Administration > Configure user accounts > User
• General tab • Roles and Permissions tab
General tab
Option Description Delete user account Click this button to delete the selected user from the list. General User name Depending on the authentication scheme, this field is editable or read-only. If the default authentication scheme is selected, you can specify the user name. For the other authentication schemes, the user name cannot be edited. Password Use this field to enter a password. This field is only available for the default authentication scheme. Full name Use this text field to optionally specify the user's full name. Email address Specify the user's email address. Version Control User Name Settings Default for all roots: This read-only field displays the list of VCS roots with the default names for the selected user. Edit Click this link to open the Version Control Username Settings page, which shows the list of the VCS roots accessible to the user, and provides controls to change or delete default user names for each VCS root. The Add new VCS username link opens Add VCS username dialog box, where you can select the desired VCS root and specify the corresponding username. Watched builds and notifications Jabber account Specify the Jabber account that will receive the notifications.
Roles and Permissions tab
Item Description Projects This column of the table shows a list of projects where the user is involved. Role This column shows the user's role in the respective project. Assign role Click this link to open the Assign Roles dialog box and assign a new role to the user in a certain project. Unassign Click this button to detach the selected roles from the user.
Document generated by Confluence on Jun 16, 2008 13:43 Page 251 See also:
• Concepts: Account | Permission | Role • UI Reference: User Account
Document generated by Confluence on Jun 16, 2008 13:43 Page 252 VCS Roots
This page last changed on Dec 05, 2007 by mio. VCS Roots
Administration > Configure VCS roots
Use this page to view the list of all VCS roots accessible to the current user, modify the existing VCS roots, attach a VCS root to or detach it from a build configuration, or to delete a VCS root.
Item Description There are accessible VCS roots TeamCity informs you about the amount of VCS roots, accessible to the current user. root, accessible to the current user, whether the root is shared between several projects or belongs to a single project, and the status of the root (not monitored, checked etc.). edit Click this link to change the selected VCS root in the Edit VCS Root page. delete Click this link to delete the selected VCS root, provided that there are no build configurations attached to it. :: Each row of a table contains an entry consisting of a project name, followed by a build configuration name. edit Click this link to change the VCS settings of the selected build configuration in the Version Control Settings page, the same as invoked as the second step of editing the build configuration. detach Click this link to remove the VCS root from the selected build configuration. Attach to build configuration Click this link to add the selected VCS root to a certain build configuration in the Choose Build Configuration dialog.
See also:
• Concepts: VCS Root | Build Configuration • System Administrator Reference: Configuring VCS Settings • UI Reference: Version Control Settings| Edit VCS Root
Document generated by Confluence on Jun 16, 2008 13:43 Page 253 Agents
This page last changed on Feb 06, 2008 by chamilton. Agents
Item Description Install build agent Click this button to install an additional build agent, using one of the suggested techniques. Refer to Installing and Running Additional Build Agents for detailed instructions.
Connected Agents
An agent is considered connected if it is registered on the TeamCity server and responds to server commands. This status is determined automatically.
This tab displays the agents which are currently connected to the TeamCity server.
Item Description Agent Displays the available agents. Click an agent link to open the agent details page. Click the column header to sort the table alphabetically by agent name. Status Displays whether the agent is enabled or disabled, and provides a link to toggle the agent's status. Click the column header to sort the table alphabetically by agent status. Disabled agents are marked with a callout icon. Hovering your mouse cursor over the icon shows summary information:
Running build Displays information about the build, which this agent is currently running. This information includes:
• the build configuration's name • status of the current build (current task, test passed or failed etc. ) Click the build status link to open the build results page. • the build progress bar. Tooltip of the progress bar shows passed and left time of the build. Stop / Run build Use this link to stop the selected build.
Disconnected Agents
An agent is considered disconnected if it was once registered on the TeamCity server, but it no longer responds to server commands. This status is determined automatically.
Document generated by Confluence on Jun 16, 2008 13:43 Page 254 This tab displays the agents which were at some point connected to the server, but currently are not connected. If an agent does not connect to the server for more than two weeks it is removed from the list.
Item Description Agent Displays the agents that are currently disconnected. Click an agent link to open the agent details page. Click the column header to sort the table alphabetically by agent name. Status Displays whether the agent is enabled or disabled, and provides a link to toggle agent status. Click the column header to sort the table alphabetically by agent status. Last registration date Displays the date and time the agent was registered by the TeamCity server. Click the column header to sort the table by the last registration date. Inactivity reason Displays textual description of the agent's inactivity reason.
Unauthorized Agents
Agents are manually authorized using the web UI. Only authorized build agents can run builds. The number of simultaneously authorized agents cannot exceed the number of agent licenses in your license pool.
This tab displays the agents that are currently not authorized, and a count of available agent licenses.
Item Description Agent Displays a list of unauthorized agents. Click an agent link to open the agent details page. Click the column header to sort the table alphabetically by agent name. Authorize Displays authorization status of an agent and a link to toggle status. Note that the agents registered for the first time are unauthorized by default. Connection status Displays whether the agent is authorized and connected, and provides a link to toggle the agent's authorization status. Hostname/IP Displays the agent's IP address or hostname. Last registration date Displays the date and time the agent was registered by the TeamCity server. Click the column header to sort the table by the last registration date. Inactivity reason Displays textual description of the agent's inactivity reason.
Agent Statistics
This feature is only available in TeamCity 3.1+
The visual metrics displayed on this page show each build agent's activity over a given time, as well as, which specific builds the agent performed.
Document generated by Confluence on Jun 16, 2008 13:43 Page 255 On this page you can:
• Mouse over a build duration to see an overview of the build results in a popup. • Navigate to the build configuration home page or the build results by clicking the links on the popup. • Select a specific time range by entering new dates (in day-month-year format) and clicking the Update button. • Sort the list by agent name or usage using the drop-down list.
Drop-down list item Description Agent name Sorts agents alphabetically by name from A to Z Agent name desc Sorts agents alphabetically by name from Z to A Agent usage Sorts agents by usage from the most inactive to the most active Agent usage desc Sorts agents by usage from the most active to the most inactive
See also:
• Concepts: Build Agent • Installation and Upgrade: Installing and Running Additional Build Agents • UI Reference: Agent Details
Document generated by Confluence on Jun 16, 2008 13:43 Page 256 Agent Details
This page last changed on Dec 05, 2007 by mio. Agent Details
Agents > click agent name
The contents of this page depend on whether the agent is connected or disconnected from the server.
Connected agent
Option Description Agent summary Status This field shows date and time that the agent was connected and enabled/disabled to the TeamCity Server. Use the link to toggle the authorized and enabled/disabled status of an agent. Details This field shows the agent's name, host name and IP address, port number and operating system. Clean sources Click the button to enforce deleting old sources from the agent before checking out the sources for the next build to be preformed by this agent. See Clean Sources. Running build This field displays information about the running build. Use the build status link to view build results. See Build Results page description. Compatible configurations Current run configuration policy Displays whether the build agent will run all compatible build configurations or only the build configurations selected from a list. Administrators can set this option using the drop-down list, while users will see the run configuration policy's status and a list of build configurations it will run. Compatible configurations This column shows the list of build configurations compatible with this build agent. Click a build configuration name to open its home page. The number in parenthesis is the number of compatible configurations. Incompatible configurations This column shows the list of build configurations that are not compatible with the current build agent, and the reason of incompatibility. Click a build configuration name to open its home page. The number in parenthesis is the number of incompatible configurations. Build runners This tab displays information about the build runners that are supported by this agent. System properties Use this tab to view the list of properties that can be used for defining build configuration requirements. For more information on system properties and using them see: System Properties of a Build Configuration. Environment variables Use this tab to view the following kinds of environment variables:
• defined in the configuration file of the agent • defined by the operating system and agent runtime
Document generated by Confluence on Jun 16, 2008 13:43 Page 257 For more information on environmental variables and using them see: System Properties of a Build Configuration.
Disconnected agent
Option Description Agent summary Status This field shows the date and time that the agent was disconnected and enabled/disabled. Use the link to toggle the enabled/disabled status of an agent. Details This field shows the agent's name, host name and IP address, port number and operating system. Clean sources Click the button to enforce deleting sources from the agent before checking out sources for the next projects built on this agent. See Clean Sources.
See also:
• Concepts: Build Agent | Run Configuration Policy • Installation and Upgrade: Installing and Running Additional Build Agents • UI Reference: Agents
Document generated by Confluence on Jun 16, 2008 13:43 Page 258 Build Configuration Home Page
This page last changed on Dec 05, 2007 by mio. Build Configuration Home Page
Item Description project name::build configuration name View the name of the project, and the name and state of the build configuration. Click the Run button to start a build on the next available agent. Click the drop-down arrow on the right side of the Run button to view a drop-down list of compatible Build Agents. Use this list to select a specific agent to run the build. Actions Click this button to select the desired action from the drop-down list:
• Pause or activate this build configuration: • Start checking now for pending changes • Enforce clean checkout for this build configuration on all build agents
Edit configuration settings Click this link to open the Edit Build Configuration page. You can opt to change certain groups of the build configuration settings by clicking the down arrow to the right and choosing one of the links from the list. Subscribe to finished builds or customize a feed Subscribe to or configure your syndication feed. Tabs • Overview • History • Change Log • Statistics • Compatible Agents • Pending Changes • Settings
Document generated by Confluence on Jun 16, 2008 13:43 Page 259 Change Log
This page last changed on Dec 03, 2007 by mio. Change Log
Build Configuration > Change Log tab
This tab shows the list of pending changes, and the changes already included in the builds of the selected build configuration:
In this page you can:
• Open the Build Results page:
• View issue in the issues database:
• View the list of changed files in the Changes tab of the Build Results page, view differences, and jump to the source code in the active IDE. The latter option is only available, if the plugin for this IDE is installed, and you are logged in to TeamCity from within this IDE:
See also:
• Concepts: Build Configuration | Build State | Change • Installing Tools: Eclipse Plugin | IntelliJ IDEA Plugin | Visual Studio Plugin • UI Reference: Build Results | My Settings And Tools
Document generated by Confluence on Jun 16, 2008 13:43 Page 260 Compatible Agents
This page last changed on Nov 28, 2007 by mio. Compatible Agents
Build Configuration > Compatible Agents tab
In this page you can:
• View compatible and incompatible agents, and navigate to the agent details:
• Jump to the Agent Requirements page of the build configuration, and change the requirements that build agents should meet to run the builds of the current build configuration..
See also:
• Concepts: Agent Requirements
Document generated by Confluence on Jun 16, 2008 13:43 Page 261 History
This page last changed on Jan 30, 2008 by chamilton. History
Build Configuration > History tab
This tab shows the complete build history of the build configuration. In this tab you can:
• Filter the build history by build tags or by the agent which performed the build:
• Open the Build Results page
• Open Build Log tab of the Build Results page, and view all messages, or important messages only:
• View and download build artifacts in the Artifacts tab of the Build Results page:
• View and download build artifacts in a popup list:
• Open the Changes tab of the Build Results page:
• Click a file link and compare versions in the differences viewer; jump to the source code in the active IDE, provided that the plugin for this IDE is installed, and you are logged in to TeamCity from within this IDE:
• View actual build start time and duration:
Document generated by Confluence on Jun 16, 2008 13:43 Page 262 • Jump to the Build Agent page and view agent details:
Document generated by Confluence on Jun 16, 2008 13:43 Page 263 Overview
This page last changed on Dec 03, 2007 by mio. Overview
Build Configuration > Overview tab
Use this tab to obtain summary information about the selected build configuration.
Item Description Current status Use this field to:
• View the number of changes pending for the selected build configuration. If there are pending changes, click the link to open the Pending Changes tab, or click the down arrow and see a list of changes in a popup window. • View the list of suitable agents. • View the current status of the build. If the current configuration does not run any builds, it is idle. If there are running builds, the list of builds display in this field. • Activate or pause build configuration
Responsible This field is available if there are failing builds. Click the Take responsibility link, if you consider yourself responsible for the problems in this build configuration.
Recent history In the Recent History section, you can:
• Open the Build Results page
• Open Build Log tab of the Build Results page, and view all messages, or important messages only:
• View and download build artifacts in the Artifacts tab of the Build Results page:
Document generated by Confluence on Jun 16, 2008 13:43 Page 264 • View and download build artifacts in a popup list:
• Open the Changes tab of the Build Results page:
• Click a file link and compare versions in the differences viewer; jump to the source code in the active IDE, provided that the plugin for this IDE is installed, and you are logged in to TeamCity from within this IDE:
• View actual build start time and duration:
• Jump to the Build Agent page and view agent details:
• View and edit build tags:
• Pin and unpin builds:
Click the links [all history] or see entire history to open the History tab. Include canceled builds Check this option to include canceled builds in the recent history list. Permalinks Create bookmarks for the following types of builds for quicker navigation:
• Last successful
Document generated by Confluence on Jun 16, 2008 13:43 Page 265 • Last pinned • Last finished
Document generated by Confluence on Jun 16, 2008 13:43 Page 266 Pending Changes
This page last changed on Nov 28, 2007 by mio. Pending Changes
Build Configuration > Pending Changes tab
Use this page to view the changes that are already committed to the version control, but not yet included in a build of the current build
configuration.
• View issue in the issues database:
• View the list of changed files in the Changes tab of the Build Results page, view differences, and jump to the source code in the active IDE. The latter option is only available, if the plugin for this IDE is installed, and you are logged in to TeamCity from within this IDE:
See also:
• Concepts: Build Configuration | Build State | Change • Installing Tools: Eclipse Plugin | IntelliJ IDEA Plugin | Visual Studio Plugin • UI Reference: Build Results | My Settings And Tools
Document generated by Confluence on Jun 16, 2008 13:43 Page 267 Settings
This page last changed on Nov 28, 2007 by mio. Settings
Build Configuration > Settings tab
Use this tab to view the build configuration settings, and quickly jump to the build configuration editing pages:
• General • Version Control • Build Runners • Build Triggering • Artifact Dependencies • Properties and Environment Variables • Agent Requirements
See also:
• Concepts: Build Configuration | Build State | Change • UI Reference: Build Results | My Settings And Tools
Document generated by Confluence on Jun 16, 2008 13:43 Page 268 Statistics
This page last changed on Feb 27, 2008 by lisar. Statistics
Build Configuration > Statistics tab
The graphs in this tab demonstrate important project statistics including: successful build rate, wait time in build queue, build duration, artifact size, and test count. The graphs show code coverage, duplicates and inspection results, if they are included in the respective build configuration. Additionally, you can extend the statistics output with custom graphs.
In the Statistics tab you can perform the following actions (see summary on the image below):
• Select time range for each type of statistics from the Range drop-down list. • Filter information by data series (for example, by agents or by result type). To do that, check or clear the desired entries in the Data Series sections. Use All and None links to select or clear all entries. • Calculate average values by checking the Average option. • Filter out failed builds and show successful builds only, by clearing the Show Failed option. Failed builds show as thin red lines. • View build summary information in tooltips and navigate to the build results page. Statistics include information about all the builds of a certain build configuration across all its history. However, according to the clean-up policy, some of the build results may be removed. In this case, you can only view the summary information about the build, but cannot jump to the build results page.
The following feature is only available in TeamCity 3.1
Document generated by Confluence on Jun 16, 2008 13:43 Page 269 Chart Types
Chart Description Success Rate This chart tracks the build success rate over the selected period of time. Build Duration Use this chart to monitor the duration of the build. Note that the build duration does not include checkout or artifact publishing time. To monitor build duration time it is best to select a single build agent or build agents with similar processors. Time spent in queue This chart tracks how long build configurations take to run after they are scheduled. This information is helpful for build agent management and prioritizing build configurations. Test Count This chart displays green, grey and red dots to track the number of tests (JUnit, NUnit, TestNG) that the build passed, ignored and failed respectively. Information on individual tests is available on the Build Results Tests tab. Artifacts Size This chart tracks the total size of all of the artifacts produced by the build. Time to fix tests This chart tracks the maximum amount of time it took to fix the tests of the particular build. If not all build tests were fixed, a red vertical stripe is displayed. This feature is only available in TeamCity 3.1 Code Coverage This chart displays blue, green, dark cyan, and purple dots to track respectively the percentages of the classes blocks, lines and methods covered by the tests. Code Duplicates This chart tracks the number of duplicates discovered in the code. Code Inspection This chart displays red and yellow dots to track respectively the number of discovered errors and warnings. Customized It is possible to display custom statistics.
See also:
• Concepts: Build Configuration | Build State | Change • System Administrator Reference: Reporting and Displaying Custom Statistic Values • UI Reference: Build Results | My Settings And Tools
Document generated by Confluence on Jun 16, 2008 13:43 Page 270 Build Queue
This page last changed on Jun 01, 2008 by ivrina. Build Queue
Option Description Use this button to move the selected build configuration to the desired position in the list. See Build Queue. Use this button to move the selected build configuration to the top position. Build configuration name Shows the name of the build configuration. Time to start Shows the estimated time that the build configuration will be queued before it starts to build and its estimated time of completion. Hovering the mouse cursor over the estimated time value shows a tooltip with expected start time and duration, and the links to the build results and build agent pages:
Triggered by Shows a brief description of the event that triggered the build. Triggers are configured in the Build triggering step of editing build configuration. The trigger can be one of the following:
• Name of the dependency build configuration. • VCS name, if VCS trigger is configured. • Scheduler, the time based triggering is configured. Can run on Shows the number of agents compatible with this build configuration. Click agent link to open Agents page, or use down arrow to quickly view the list of compatible agents in the popup window. Remove Use this column to delete unnecessary builds from the queue.
Enhancements in TeamCity 3.1
The Build Queue tab was improved between TeamCity 3.0 and TeamCity 3.1. The following feature is only available in TeamCity 3.1.
The Build Queue now contains a number column that displays each build's position in the queue.
Document generated by Confluence on Jun 16, 2008 13:43 Page 271 Build Results
This page last changed on Jan 14, 2008 by lisar. Build Results
This page is available from the build result link on the Projects and My Changes pages.
There is a Run button and a build history interface in the top right corner of the page. Click the Run button to re-run the current build configuration. Click the guillemets (angle quotes) on the build history interface to navigate to Build Results pages of the previous and next builds (identified with their build state and number), or click the All history link to view the build history tab of the build configuration home page.
This page contains a number of tabs with the particular build information. The Overview, Changes, and Build Log tabs appear for every build on every page. Additional tabs, such as Artifacts, Code Inspection, Dependencies, Duplicates, Tests will be available depending on the build script, build runner, and build configuration:
Third-party reports can also be configured to appear in customized tabs. For more information see: Displaying Third-Party Reports in a Build Result Tab
Document generated by Confluence on Jun 16, 2008 13:43 Page 272 Artifacts tab
This page last changed on Nov 29, 2007 by chamilton. Artifacts tab
There is a Run button and a build history interface in the top right corner of the page. Click the Run button to re-run the current build configuration. Click the guillemets (angle quotes) on the build history interface to navigate to Build Results pages of the previous and next builds (identified with their build state and number), or click the All history link to view the build history tab of the build configuration home page.
The Artifacts tab appears on the Build Results page if the build created artifacts. This tab is used to view all of the build artifacts. Click + or - to expand or collapse any directories; click the file name link to download the selected build artifact.
Document generated by Confluence on Jun 16, 2008 13:43 Page 273 Build Log tab
This page last changed on Nov 29, 2007 by chamilton. Build Log tab
There is a Run button and a build history interface in the top right corner of the page. Click the Run button to re-run the current build configuration. Click the guillemets (angle quotes) on the build history interface to navigate to Build Results pages of the previous and next builds (identified with their build state and number), or click the All history link to view the build history tab of the build configuration home page.
The Build Log tab appears on the Build Results page and is a quick way to view all of the information that was generated when the build was run.
Item Description Download full build log link Click this link to download the complete build log. Important messages link Click this link to view only warnings, error messages, and the final build status message. All messages link Click this link to show all of the information that was generated during the build process.
Document generated by Confluence on Jun 16, 2008 13:43 Page 274 Changes tab
This page last changed on Nov 29, 2007 by chamilton. Changes tab
There is a Run button and a build history interface in the top right corner of the page. Click the Run button to re-run the current build configuration. Click the guillemets (angle quotes) on the build history interface to navigate to Build Results pages of the previous and next builds (identified with their build state and number), or click the All history link to view the build history tab of the build configuration home page.
The Changes tab appears on the Build Results page and shows the list of changes included in build. The header of each entry contains the following information:
By default, the headers are collapsed. Being expanded, each entry shows:
• VCS comment. Besides textual information, a comment can be mapped to an external link. • Date and time of build completion. • Number of modified files and type of change (edited, added, deleted) • List of changed files links. Click a file link to open the file in the differences viewer. Click to open the source code in the currently active IDE.
See also:
• Concepts: Change • UI Reference: Build Results
Document generated by Confluence on Jun 16, 2008 13:43 Page 275 Code Coverage tab
This page last changed on Dec 05, 2007 by mio. Code Coverage tab
There is a Run button and a build history interface in the top right corner of the page. Click the Run button to re-run the current build configuration. Click the guillemets (angle quotes) on the build history interface to navigate to Build Results pages of the previous and next builds (identified with their build state and number), or click the All history link to view the build history tab of the build configuration home page.
This tab shows the full HTML code coverage report, generated by Emma. Such reports appear in the Build Results, when code coverage build runner is enabled for a build configuration. You can also open this tab using the View full coverage report link in the Overview tab.
You can opt to include source code in the generated report. This is done in the Coverage info section of a build runner editing page, which is available for Ant, Maven2 and Ipr build runners.
Document generated by Confluence on Jun 16, 2008 13:43 Page 276 Code Inspection tab
This page last changed on Feb 19, 2008 by chamilton. Code Inspection tab
There is a Run button and a build history interface in the top right corner of the page. Click the Run button to re-run the current build configuration. Click the guillemets (angle quotes) on the build history interface to navigate to Build Results pages of the previous and next builds (identified with their build state and number), or click the All history link to view the build history tab of the build configuration home page.
The Code Inspection tab appears on the Build Results page and is used to examine the code review provided by the inspection build runner.
The Code Inspection tab is split into two sections: A list of inspections (on the left) and a list of files containing the issues found by the selected inspection (on the right).
Item Description Total Select this radio button to display the inspections that generated both errors and warnings. The numbers in parenthesis show the number of new issues discovered in this build followed by the number of issues solved since the last build. Errors Select this radio button to display only the inspections that generated errors. The numbers in parenthesis show the number of new errors discovered in this build followed by the number of errors fixed since the last build. new only Select this option to display errors or warnings that were introduced since the previous build. Expand the inspection name to show the issues discovered during the code review. Click the issue name to select that issue and show a list of files that contain that problem in the right side of tab. The line of code that contains the problem is listed under the file name. Click this number to jump the code in your IDE.
Enhancements in TeamCity 3.1
The Code Inspection tab was improved between TeamCity 3.0 and TeamCity 3.1. The following feature is only available in TeamCity 3.1.
• Scope Filter
Document generated by Confluence on Jun 16, 2008 13:43 Page 277 The improved interface includes a scope filter in the the upper-left corner. This filter lists the specific directories that contain issues that were discovered during the code inspection. This filtering makes it easier for developers to manage specific code for which they might be responsible.
Document generated by Confluence on Jun 16, 2008 13:43 Page 278 Dependencies tab
This page last changed on Mar 04, 2008 by ivrina. Dependencies tab
There is a Run button and a build history interface in the top right corner of the page. Click the Run button to re-run the current build configuration. Click the guillemets (angle quotes) on the build history interface to navigate to Build Results pages of the previous and next builds (identified with their build state and number), or click the All history link to view the build history tab of the build configuration home page.
The Dependencies tab appears on the Build Results page if the build has artifact dependencies. This tab contains a list of builds that created the artifacts required by this build.
Item Description Build Results link Click to navigate to the Build Results pages of the build listed below it. Artifacts link Click the link to jump to the Artifacts tab of that build, or click the drop-down arrow to view a popup list of artifacts. Click an artifact to download it.
Document generated by Confluence on Jun 16, 2008 13:43 Page 279 Duplicates tab
This page last changed on Feb 19, 2008 by chamilton. Duplicates tab
There is a Run button and a build history interface in the top right corner of the page. Click the Run button to re-run the current build configuration. Click the guillemets (angle quotes) on the build history interface to navigate to Build Results pages of the previous and next builds (identified with their build state and number), or click the All history link to view the build history tab of the build configuration home page.
The Duplicates tab appears on the Build Results page and is used to examine the code review provided by the Duplicates build runner.
The tab is split into the following sections:
• A list of duplicates found. The new only option enables you to show only the duplicates that appeared in the latest build. • A list of files containing these duplicates. Use the left and right arrow buttons to show selected duplicate in the respective pane in the lower part of the tab • Two panes with the source code of the file fragments that contain duplicates. The button opens the selected file in the active IDE.
Enhancements in TeamCity 3.1
The Duplicates tab was improved between TeamCity 3.0 and TeamCity 3.1. The following features are only available in TeamCity 3.1.
• Scope Filter The improved interface includes a scope filter in the the upper-left corner. This filter lists the specific directories that contain the duplicates. This filtering makes it easier for developers to manage specific code for which they might be responsible. • Syntax Highlighting The syntax of the code seen the duplicates viewer is now highlighted.
Document generated by Confluence on Jun 16, 2008 13:43 Page 280 See also:
• Concepts: Code Duplicates • UI Reference: Java Duplicates Finder | .NET Duplicates Finder
Document generated by Confluence on Jun 16, 2008 13:43 Page 281 Overview tab
This page last changed on Dec 05, 2007 by mio. Overview tab
There is a Run button and a build history interface in the top right corner of the page. Click the Run button to re-run the current build configuration. Click the guillemets (angle quotes) on the build history interface to navigate to Build Results pages of the previous and next builds (identified with their build state and number), or click the All history link to view the build history tab of the build configuration home page.
The top part of the tab is color coded (green if the build passed all the test, red if it failed, and blue if it is still running). Finished builds
Item Description Result Shows the build result message and status icon. Time Shows the build's start time and the duration it took to build. Agent Link to the agent that ran the build. Clicking this link opens the Agent Details page. Triggered Shows what triggered the build, and when it happened. Pin status Use Pin/Unpin link to toggle pinned status of the build result. Tags View any build tags that have been assigned to the build, and edit tags. Running builds
Item Description Hanging build notification If a build is probably hanging, the following notification appears on top of the Overview tab: Started Shows build start time and status icon. Use Stop build link to kill the entire build process, in case something goes wrong. To investigate the issue, use Thread dump link. Time left Shows estimated time left to build completion (passed and estimated total time in brackets) Agent Link to the agent that is running the build. Clicking this link opens the Agent Details page. Triggered Shows what triggered the build, and when it happened. Responsible This field is available for the failing builds. Click the Take responsibility link, if you consider yourself responsible for the problems in this build. Thread dump Click the View thread dump link to view the process tree of the running build, and thread dumps of each Java or .Net process in a separate frame. If the process is not Java or .Net, its command line is retrieved. The possibility to view thread dump is supported for the following platforms:
Document generated by Confluence on Jun 16, 2008 13:43 Page 282 • Windows, with JDK 1.3 and higher • Windows, with JDK 1.6 and higher, using jstack utility • Non-Windows, with JDK 1.5 and higher, using jstack utility
Running step Shows the current step of the build procedure. If another build of this same build configuration is concurrently running, a small window will appear with the following information:
• The build results of that build linking to the build results page; • A changes link with a drop-down list of changes included in that build; • The build number, time of start, and a link to the agent it is running on.
Either of the above sections is followed by an overview of tests, code coverage and/or duplicates search if they are part of the build configuration. Failed tests provide links to where they can be viewed in the web UI or the IDE. Failed tests that have been fixed will appear as struck-through text and will list the build in which the fix first appeared.
The overview of tests includes information about the failed, ignored and passed tests:
Expand the failed tests node to see the details:
See also:
• UI Reference: Build Results
Document generated by Confluence on Jun 16, 2008 13:43 Page 283 Tests tab
This page last changed on Mar 04, 2008 by ivrina. Tests tab
There is a Run button and a build history interface in the top right corner of the page. Click the Run button to re-run the current build configuration. Click the guillemets (angle quotes) on the build history interface to navigate to Build Results pages of the previous and next builds (identified with their build state and number), or click the All history link to view the build history tab of the build configuration home page.
This tab is included on the Build Results page, if tests were run.
The snapshot above is actual for the TeamCity 3.1 version.
Item Description Find Type a particular test name and click Filter to view only a limited number of tests. Items to show Use the drop-down list to select the number of tests to be displayed on each page. Click OK to save the selection. Status Shows the status (OK, Ignored, and Failure) of the test. Failed tests result in a red Failure link, which can be followed to view the stacktrace. Click the header above this column to sort the table by status. Test Click the button next to the test name and test package to open the test in your IDE. Click the header above this column to sort by test name. Duration Shows the time it took to complete the test. Click the button to show the Test Duration Graph popup (see below). Click the header above this column to sort by duration. Order# Shows the sequence in which the tests were run. Click the header above this column to sort by test order number.
Document generated by Confluence on Jun 16, 2008 13:43 Page 284 Test Duration Graph
The test duration graph is useful for comparing the amount of time it takes individual tests to run on the builds of this build configuration.
Test duration results are only available for the builds which are currently in the build history. Once a build has been cleaned up this data is no longer available.
You can perform the following actions on the Test Duration Graph:
• Filter out the builds that failed the test by clearing the Show failed option. • Calculate the daily average values by selecting the Average option. • Click a build's test duration dot plotted on the graph to jump to the corresponding build results Build Results page. • View a build summary in the tooltip of a build's test duration dot, and navigate to the corresponding Build Results page. • Filter information by agents by selecting or clearing a particular agent or by clicking All or None links to select or clear all agents.
Document generated by Confluence on Jun 16, 2008 13:43 Page 285 My Changes
This page last changed on Nov 29, 2007 by mio. My Changes
This page shows last 5 days when the current user was active and introduced changes, already included
in builds.
Summary status of the project builds provides the following information:
• Build state icon • Your check-in comment • VCS name • Change list number • VCS root name displays in a popup on pointing to the icon • Date and time of your commit • Number of changed files, included in build. From the drop-down list, you can view differences or open a file in an active IDE.
In this page you can:
• Open build configuration page:
• View the number of the current attempt to create the build, and information about the first attempt. From this popup frame, you can view build results, changes information and agent details.
• View build results, test results and build log:
• View changes, included in this build
• View issue in the issues database:
Document generated by Confluence on Jun 16, 2008 13:43 Page 286 • View the list of changed files in the Changes tab of the Build Results page, view differences, and jump to the source code in the active IDE. The latter option is only available, if the plugin for this IDE is installed, and you are logged in to TeamCity from within this IDE:
• View agent details:
See also:
• Concepts: Build State | Change
Document generated by Confluence on Jun 16, 2008 13:43 Page 287 My Settings And Tools
This page last changed on May 20, 2008 by ivrina. My Settings And Tools
• General tab ° General ° Watched Builds and Notifications ° Version Control Settings ° TeamCity Tools • Roles tab
General tab
General
Option Description Username Depending on the authentication scheme, this field is editable or read-only. If the default authentication scheme is selected, you can specify the user name. For the other authentication schemes, user name is not editable. Password Use this field to enter password. This field is only available for the default authentication scheme. Full name Specify optional full name.
Watched Builds and Notifications
This section shows the list of all notifiers and the state of your subscription (number of watched projects and notification conditions).
Note Email and Jabber notifications will be sent only after TeamCity server email and Jabber settings has been configured in the Administration page. The administrator can also customize Email and Jabber notification templates. Option Description Email Notifier Use this section to configure watched builds and notification rules for the email notification. IDE Notifier Use this section to configure watched builds and notification rules for the notification via IDE plugins. Jabber Notifier Use this section to configure watched builds and notification rules for the Jabber notification, and specify your Jabber account. Windows Tray Notifier Use this section to configure watched builds and notification rules for the notification via Windows Tray. edit Click this button to change selected notifier settings in the Notifier Settings page.
Version Control Username Settings
This section displays the user names you use in the supported Version Control Systems. The login name is used by default. Make sure the user names are correct, otherwise you will not be able to track your changes status in the My Changes view.
Document generated by Confluence on Jun 16, 2008 13:43 Page 288 TeamCity Tools
The sidebar section lists all TeamCity tools that ship with the product, and provides links for downloading or customization:
• IntelliJ IDEA plugin • Windows Tray Notifier • Visual Studio 2005 plugin • Eclipse plugin • Syndication feed
Refer to the Installing Tools section for installation details.
Roles tab
This tab displays a list of projects and the corresponding role (set of permissions) the user has for each project. Roles are assigned to the user by the system administrator.
Use this page to configure syndication feed to get information about builds. The values specified in the fields of this page are used to generate the Feed URL.
Item Description Select Build Configurations List build configurations Specify which build configurations display in the field Select build configurations or projects. The following options are available:
• With external status enabled: if this option is selected, the next field shows the list of build configurations, for which the option Enable status widget in the Create / Edit Build Configuration page is set to true, and the build configurations are visible for everybody without authentication. • Available to 'Guest' user: Select this option to show the list of build configurations, which are visible to the user with the Guest permissions. • All: Select this option to show a complete list of build configurations, which requires HTTP authorization. Selecting this option enables the field Feed authentication settings.If external status for the build configuration is not enabled, the feed will be available only for authorized users. Select build configurations or projects Use this list to select the build configurations or projects you want to be informed about via syndication feed. Feed Entries Selection Generate feed items for Specify the events, which trigger syndication feed generation. You can opt to select builds, changes or both. Include builds Specify the types of builds to be informed about:
• All builds • Only successful • Only failed Only builds with changes of the user Select the user, whose changes you want to be notified about. You can get syndication feed about the changes of all users, yours only, or of a particular user from the list of users registered to the server. Other Settings The following options are only available, when All is selected in the List build configurations section. Include credentials for HTTP authentication Check this option to specify the user name and password for automatic authentication. If this option is not checked, you will have to enter your user name and password in the authorization dialog box of your feed reader.
Document generated by Confluence on Jun 16, 2008 13:43 Page 290 TeamCity User, Password Type the user name and password, which will be used for HTTP authorization. These fields are only available, when Include credentials... option is checked. Copy and paste URL to your feed reader, or This field displays a URL, generated by TeamCity, Subscribe on the base of the values, specified above. You can either copy and paste it to your feed reader, or click the Subscribe link.
See also:
• Concepts: RSS Feed • Working with Tools: Syndication Feed
Document generated by Confluence on Jun 16, 2008 13:43 Page 291 Notifier Settings
This page last changed on Feb 19, 2008 by chamilton. Notifier Settings
My Settings and Tools > Watched Builds and Notifications > edit
Use this page to view and change the list of projects you want to monitor, and the events to be notified about. Builds to watch and notification rules
Option Description Builds you are watching Displays the project and build configuration in the format :: Send notification when Displays the list of events that trigger notification. If no events are selected, the notification rule is disabled, and you have to click the edit button to specify the triggering events. edit Click this button to change selected notification rule in the Edit rule section of the same page. delete Click this button to delete selected notification rule. Add new rule Click this button to create a new notification rule in the Add rule section of the same page. Configure other notifiers Click this button to display the list of available notifiers and navigate to the settings page of the selected notifier.
Add / Edit Rule
This section was restructured between versions 3.0 and 3.1. Please refer to the applicable description: 3.0 or 3.1.
Add / Edit Rule in Version 3.0
Option Description Watch builds Use this section to define which builds you want to monitor. Watch builds with my changes Select this radio button to monitor only the builds that contain your changes. Note When Watch builds with my changes is selected, you will not receive notifications about subsequent failed builds if they fail with the same errors. Watch builds from selected build configurations Select this radio button to monitor all of the builds of the selected project and build configurations in the drop-down menu. Send notification when Use this section to define notification conditions. The build fails Check this option to receive notifications about all of the failed builds in the specified projects and build configurations. Tip If the Watch builds with my changes option is selected, you will not receive notifications about the next failed builds if
Document generated by Confluence on Jun 16, 2008 13:43 Page 292 they fail with the same errors. If someone takes responsibility for a failed build, all the subsequent notifications will be sent only to that developer. Ignore failures not caused by my changes Check this option not to be notified when other people's changes caused a build of the specified build configurations to fail. Notify when the first error occurs Check this option to receive notifications when the first errors are detected, even before the build has finished. Build successful Check this option to receive notifications when a build of the specified build configurations has executed successfully. Build starts Check this option to receive notifications when a build of the specified build configurations starts. The build is probably hanging Check this option to receive notifications when TeamCity suspects that a build of the specified build configurations is hanging. Responsibility changes Check this option to receive notifications about the responsible person's activities, like "responsibility taken", "problems fixed", "gave up", and the first successful build after the fixes. Important!
Notification rules are applied in the order they are presented in the Watched builds and configurations table. The most specific rules are those set for specific build configurations; then go rules for all build configurations of a project; notifications for builds with my changes are the least specific.
Add / Edit Rule in Version 3.1
Option Description Watch builds Use this section to define which builds you want to monitor. Watch builds with my changes Select this radio button to monitor only the builds that contain your changes. Note When Watch builds with my changes is selected, you will not receive notifications about subsequent failed builds if they fail with the same errors. Watch builds from selected build configurations Select this radio button to monitor all of the builds of the selected project and build configurations in the drop-down menu. To select multiple build configurations hold down the Ctrl key. Select - All projects - in the drop-down menu to monitor all of the builds of all the projects' build configurations. Send notification when Use this section to define notification conditions. The build fails Check this option to receive notifications about all of the failed builds in the specified projects and build configurations. Tip If the Watch builds with my changes option is selected, you will not receive notifications about the next failed builds if they fail with the same errors. If someone takes responsibility for a failed build, all the subsequent notifications will be sent only to that developer.
Document generated by Confluence on Jun 16, 2008 13:43 Page 293 Ignore failures not caused by my changes Check this option not to be notified when other people's changes caused a build of the specified build configurations to fail. Only notify on the first failed build after successful Check this option to be notified when the build fails after a successful build. By selecting this option you will not be notified about subsequent failed builds. Build successful Check this option to receive notifications when a build of the specified build configurations has executed successfully. Only notify on the first successful build after failed Check this option to be notified when the build is successful after a failed build. By selecting this option you will not be notified about subsequent successful builds. Notify when the first error occurs Check this option to receive notifications when the first errors are detected, even before the build has finished. Build starts Check this option to receive notifications when a build of the specified build configurations starts. The build is probably hanging Check this option to receive notifications when TeamCity suspects that a build of the specified build configurations is hanging. Responsibility changes Check this option to receive notifications about the responsible person's activities, like "responsibility taken", "problems fixed", "gave up", and the first successful build after the fixes. Important!
Notification rules are applied in the order they are presented in the Watched builds and configurations table. The most specific rules are those set for specific build configurations; then go rules for all build configurations of a project; notifications for builds with my changes are the least specific.
Document generated by Confluence on Jun 16, 2008 13:43 Page 294 Projects
This page last changed on Feb 20, 2008 by chamilton. Projects
The Projects tab shows a list of projects and their build configurations. Build configurations can be expanded to show the status of running builds and the last completed build.
Certain options will only be visible if the user has permission to use them. For example, guest users in TeamCity Professional will not see the Run button, Stop build and Configure Visible Projects links and will not be able to view web diffs of changes. The same limitations apply to users with only project viewer or agent manager roles in TeamCity Enterprise. If users in TeamCity Enterprise have been assigned project developer or project administrator roles in specific projects, then these features will be available to them on those particular projects.) Option Description Configure Visible Projects Click this link to open a popup with a list of all the projects. Select the check boxes of the projects to be displayed on the page or click and drag the
button to reposition the project on the list. Click Close to save your settings and close the popup. View all projects Click this link to open a popup with a list of all of the projects, regardless whether they are visible or not. Collapse all Click this link to hide all of the build results from the page view. Expand all Click this link to show the status of running builds and the last completed build. Hide project Removes the project from the page view. Hint: Use Configure Visible Projects to restore hidden projects. Build configuration option Description Hide the build configuration's build results
Show the build configuration's build results
Build configuration name Click this link to navigate to the Build Configuration home page in queue This link appears when a build is in the build queue. Click this link to navigate to the Build Queue tab. Pending This link appears when modifications are ready to be integrated in the next build. Click this link to navigate to the pending changes tab on the build configuration's page, or click the drop-
Document generated by Confluence on Jun 16, 2008 13:43 Page 295 down arrow to open a popup list of pending changes. Click the drop-down arrow to the right of a specific pending change to view a popup list of the files that were edited. Click the link to open the web diff in a separate page or click to open the file in your IDE. Click the Run button to start a build on the next available agent. Click the drop-down arrow on the right side of the Run button to view a drop-down list of compatible Build Agents. Use this list to select a specific agent to run the build. Build results option Description Build status The status of running builds are available in real time. Click this link to navigate to the Build Results page, or click the drop-down arrow just to the right of the build results to view a list of specific tabs on the Build Results page that you can navigate to directly. Artifacts This link appears if the build created artifacts. Follow this link to the Artifacts tab on the Build Results page, or click the drop-down arrow to the right of the link to open a popup list of artifacts and links to them. Changes This link appears if changes were integrated into the build. Click this link to navigate the Changes tab on the Build Results page, or click the drop- down arrow to open a popup list of changes. If the previous build failed, this popup may contain two tabs showing which changes were made In this build and Since last successful build. Click the drop-down arrow to the right of a specific change to view a popup list of the files that were edited. Click the link to view a web diff in a separate page or click to open the file in your IDE. Build time/duration Shows the time the build was started and the duration it took to build. If the build is currently running it will show the start time and a progress bar. The tool tip will display the build's elapsed time and an estimated amount of time it will take to finish. Stop build This link appears if the build is currently running. Click this link to abort the build. A comment window will appear. Comments will be visible on the Build Results page.
Enhancements in TeamCity 3.1
The Projects tab was improved between TeamCity 3.0 and TeamCity 3.1. The following features are only available in TeamCity 3.1.
The View All Projects link has been replaced with a drop-down arrow on the Projects tab button. This drop-down arrow will display all of the projects regardless of whether they are visible on the Projects tab or not.
Document generated by Confluence on Jun 16, 2008 13:43 Page 296 The builds in-queue drop-down arrow appears on the build configuration heading and displays a popup with build queue information. Descriptions of elements on this popup can be found on the Build Queue section in the documentation.
See also:
• Concepts: Build State | Build Configuration State
Document generated by Confluence on Jun 16, 2008 13:43 Page 297
