Configuring General Settings
When creating a build configuration, specify the following settings:
Setting | Description |
|---|---|
Name | The build configuration name. |
Build Configuration ID | A unique ID of the configuration across all build configurations and templates in the system automatically generated from the build configuration name, but can also be set manually. |
Description | An optional description for the build configuration. |
Build Number Format | A pattern which is resolved and assigned to the build number on the build start. |
Build Counter | Specify the counter to be used in build numbering. Each build increases the build counter by 1. Use the Reset link to restore the counter value to 1. |
Publish Artifacts | Select when to publish artifacts:
This setting does not affect artifacts publishing configured in a build script.
|
Patterns to define artifacts of a build. After the first build is run, you can browse the agent checkout directory to configure artifacts paths. | |
Specify additional options for the builds of this build configuration. |
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:
Pattern | Description |
|---|---|
| The build counter unique for each build configuration. It is maintained by TeamCity and will resolve to a next integer value on each new build start. The current value of the counter can be edited in the Build counter field. |
| The revision used for the build of the VCS root with |
| A value of the build property with the corresponding name. All the Predefined Build Parameters are supported (including Reference-only server properties). |
tip
A build number format example:
1.0.%build.counter%.%build.vcs.number.My_Project_svn%.
Though not required, it is still highly recommended ensuring the build numbers are unique. Please include the 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, refer to Build Script Interaction with TeamCity.
Build artifacts are files produced by the build which are stored on TeamCity server and can be downloaded from the TeamCity UI or used as artifact dependencies by other builds. On the General Settings page of the build configuration, you can specify patterns for the files on the agent which will be uploaded to the server after the build.
If you have a finished build on an agent, you can use the checkout directory browser 
(which lists the checkout directory content on the agent) and select artifacts from the tree. TeamCity will place the paths to them into the input field.
The Artifact Paths field supports relative (to the build checkout directory) and absolute paths. Using relative paths is recommended. You can specify exact file paths or patterns, one per line or comma-separated. Patterns support the * and ** wildcards (see below). Each line can be of the form [+:]source [=> target] to include and -:source [=> target] to exclude files or directories to publish as build artifacts. The parts enclosed in square brackets are optional. Rules are grouped by the right part and are applied in the order of appearance:
+:**/* => target_directory
-:directory1 => target_directorywill tell TeamCity to publish all files except for directory1 into the target_directory.
Line format description:
file_name|directory_name|wildcard [ => target_directory|target_archive ]Note that although absolute paths are supported in the source part, it is recommended to use paths relative to the build checkout directory.
file_name— to publish the file. The 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 Ant-like wildcard pattern (only*and**wildcards are 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.You can use build parameters in the artifacts' specification. For example, use
mylib-%system.build.number%.zipto refer to a file with the build number in the name.
The optional part starting with the => symbols and followed by the target directory name can be used to publish the files into the specified target directory. If the target directory is omitted, the files are published in the root of the build artifacts. You can use . (dot) as a reference to the build checkout directory.
The target paths cannot be absolute. Non-relative paths will produce errors during the build.
target_directory— (optional) the directory in the resulting build's artifacts that will contain the files determined by the left part of the pattern.target_archive— (optional) 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 astarget_archivewhenever it ends with a supported archive extension, that is.zip,.7z,.jar,.tar.gz, or.tgz.
warning
There is a known issue with inability to exclude artifact paths specified with the
**wildcard: for example,-:**/directory. Such exclude rules will be ignored by TeamCity. As a workaround, use the-:**/directory/**format instead. See the related issue in our tracker.
A symbolic link (symlink or soft link) is a Linux file that points to other files or directories and represents their absolute or relative path. If a directory that you need to publish as a build artifact contains symlinks, you can choose one of two possible modes:
Published archives include symlinks as symlinks. This is the default behavior. You can explicitly decorate an artifact path with the
teamcity:symbolicLinksattribute to force this behavior.#teamcity:symbolicLinks=as-is %teamcity.build.checkoutDir%/build=>build.zipPublished archives include files and folders referenced by symlinks. To enable this behavior, decorate an artifact rule with the
teamcity:symbolicLinksattribute as follows.#teamcity:symbolicLinks=inline %teamcity.build.checkoutDir%/build=>build.zip
Note that attributes affect only artifact publishing rules declared directly beneath them. For example, in the sample below only Archive_A will contain files and folders referenced by symlinks. Archive_B will employ the default behavior and include symlinks as files.
#teamcity:symbolicLinks=inline
Dir_A=>Archive_A.zip
Dir_B=>Archive_B.zipinstall.zip— publish a file namedinstall.zipin the build artifacts.dist— publish the content of the dist directory.target/*.jar— publish alljarfiles 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 thedocsdirectory.reports => reports, distrib/idea*.zip— publish reports directory as reports and files matchingidea*.zipfrom thedistribdirectory into the artifacts root.Relative paths inside a zip archive can be used, if needed:
results\result1\Dir1\Dir2 => archive.zip!results/result1/Dir1.The same
target_archivename can be used multiple times, for example:+:*/*.html => report.zip+:*/*.css => report.zip!/css/-:*/*.txt => report.zip
The following options are available to build configurations:
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 the estimated average run time and if the build has not sent any messages since the estimation was 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 would have enough information to estimate the average run time.
You can restrict running personal builds by unchecking the allow triggering personal builds option (on by default).
This option enables retrieving the status and basic details of the last build in the build configuration without requiring any user authentication. Note that this also allows getting the status of any specific build in the build configuration (however, builds cannot be listed and no other information except the build status (success/failure/internal error/cancelled) is available).
The status can be retrieved via the HTML status widget described below, or via a single icon: with the help of REST API or via the Actions menu in Build Configuration Home.
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.
When the Enable status widget option is enabled, an HTML snippet can be included into an external web page and will display the current build configuration status.
For build status icon as a single image, check REST build status icon.
The following build process information is provided by the status widget:
The latest build results
Build number
Build status
Link to the latest build artifacts. The 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 thewithCss=trueparameter 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 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=1parameter and useiframeinstead of the script:<iframe src="<TeamCity_server_URL>/externalStatus.html"/>If you want to include default CSS styles without modifying the
<head>section, add thewithCss=trueparameter.
To provide up-to-date status information on specific build configurations, use the following parameter in the URL as many times as needed:&buildTypeId=<external build configuration ID>
It is also possible to show the status of all projects build configurations by replacing &[buildTypeId](identifier.md)=<external build configuration ID> with &[projectId](identifier.md)=<external project ID>. 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). However, in this case, you must not include the withCss=true parameter, but provide the CSS styles explicitly, preferably in the <head> section, instead.
You can limit the number of builds that can run simultaneously on all agents. This option helps improve allocating resources for your builds and avoid the situation when all agents are busy with the builds of a single project.
You can limit the total number of builds for a build configuration and configure granular limits per branch using the related fields:
for a build configuration, enter the total maximum number of builds. The number is set to 0 by default allowing an unlimited number of builds to run simultaneously.
for a build limit per branch, enter the new-line separated list of rules. Each rule must follow the
branch:numberpattern, wherebranchis either a logical branch name or a pattern containing an * andnumberspecifies the maximum number of builds which can run simultaneously in each branch matching the pattern. 0 allows an unlimited number of builds in the specified branch.