Configuring General Settings

When creating a build configuration, on the first page of the wizard specify the following options:

Name and Description

Use these fields to provide the name for the build configuration and optional description. Note that the Name field should not contain special characters.

Build Number Format

In the Build number format field you can specify a pattern which is resolved and assigned to the build number on the build start.

The following substitutions are supported in the pattern:

Though not required, it is still highly recommended to ensure the build numbers are unique. Please include build counter in the build number and do not reset the build counter to lesser values. It is also possible to change the build number from within your build script. For details please refer to the Build Script Interaction with TeamCity page.

Build Counter

Use the Build counter field to specify the counter to be used in the build numbering. Each build increases the build counter by 1. Use the Reset counter link to reset counter value to 1.

Artifact Paths

To learn what is called a build artifact in TeamCity, please refer to the Build Artifact concept page. On the General Settings page of the build configuration you can specify artifacts of a build using comma-, or newline- separated values of the format:

file_name|directory_name|wildcard [ => target_directory|target_archive ]

The format contains:

• file_name — to publish the file. The file name should be relative to the build checkout directory.

• directory_name — to publish all the files and subdirectories within the directory specified. The directory name should be a path relative to the build checkout directory. 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 Wildcards pattern ("" and "*" wildcards are only supported). The wildcard should represent a path relative to the build checkout directory. The files will be published preserving the structure of the directories matched by the wildcard (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.

• target_archive — the path to the archive to be created by TeamCity by packing build artifacts determined in the left part of the pattern. TeamCity treats the right part of the pattern as target_archive whenever it ends with a supported archive extension, i.e. .zip, .jar, .tar.gz, or .tgz.

The names can be paths relative to the Build Checkout Directory or absolute paths. The usage of absolute paths is discouraged, please try to use path 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.

You can use Configuring Build Parameters in the artifacts specification. For example, use "mylib-%\system.build.number%.zip" to refer to a file with the build number in the name.

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.

Fail Build Conditions

In the Fail build if area specify how TeamCity should fail builds:

• 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. Regardless of this option, TeamCity will run all build steps.

• 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.

• an out of memory or crash is detected (Java only): Check this option to mark the build as failed if a crash of the JVM is detected, or Java out of memory problems. If possible, TeamCity will upload crash logs and memory dumps as artifacts for such builds.

Other Build Options

Specify additional options for the builds of this build configuration.

Hanging Build Detection

Select the Enable hanging build detection option to detect probably "hanging" builds. A build is considered to be "hanging" if its run time significantly exceeds estimated average run time and the build did not send any messages since the estimation exceeded. To properly detect hanging builds TeamCity has to estimate the average time builds run based on several builds. Thus if you have a new build configuration, it may make sense to enable this feature after a couple of builds have run, so that TeamCity will have enough information to estimate the average run time.

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.

Enable Status Widget

Check the Enable status widget option to enable retrieving the status of the latest build to an external web page. This feature allows you to get an overview of the current project status on your company's website, wiki, Confluence or any other web page. By means of the status widget, the following build process information is provided:

• The latest build results,

• Build ID,

• Build data,

• Link to the latest build artifacts. Status widget doesn't require users log in to TeamCity.

When the feature is enabled, you need to include the following snippets of code in the web page source:

• Add this code sample in the <head> section (or alternatively, add the withCss=true parameter to externalStatus.html): <style type="text/css"> @import "<TeamCity_server_URL>/css/status/externalStatus.css"; </style>

• Insert this code sample where you want to display the build configuration's status: <script type="text/javascript" src="<TeamCity_server_URL>/externalStatus.html?js=1"> </script>

• If you prefer to use plain HTML instead of javascript, omit the js=1 parameter and use iframe instead of script: <iframe src="<TeamCity_server_URL>/externalStatus.html"/>

• If you want to include default CSS styles without modifying the <head> 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=<buildConfigurationId>

It is also possible to show the status of all a project's build configurations by replacing "&buildTypeId=<buildConfigurationId>" with "&projectId=<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 (for example, 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 <head> section, instead.

Enabling the status widget also allows non-logged in users to get RSS feed for the build configuration.

See also:

Concepts: Build Configuration