Thursday, 15 August 2019

Introduction to TeamCity

Build Configuration

All paths in build configuration settings should be relative paths (relative to the build checkout directory). The checkout directory is the directory where all the sources (configured as VCS roots) are placed by the TeamCity.

General Settings

Name (text field)

This is a custom name of this build configuration.

Build configuration ID (text field)

Default value is in form: ProjectName_SubProjectName_BuildConfigurationName

Description (text field)

This is a custom description of this build configuration.

Build configuration type (combo box)

This can have one of these 3 values:
  • Regular
  • Composite (aggregating results)
  • Deployment

Build number format (text field)


Build counter (text field)

Publish artifacts (combo box)

3 options are available:

  • Even if build fails
  • Only if build status is successful
  • Always, even if build stop command was issued

Artifact paths (text field)

The build artifacts are files that you want to publish as the results of your build. If the build generates it's output in the folder named "output", you can just set "output" as your artifacts path.

Let's assume that some build step creates directory output/content and this is the place where artifacts are stored. If value of this field is set to:

output/content => content

...then upon successful build, in the build list view, we can see for this build an Artifacts icon enabled and if we click on it, we can see a folder named content which we can expand and see its content.


Build step >> Working Directory: ./output/
Build step >> Custom script: mkdir -p ./dirA/ && echo "content1" > ./dirA/file1
Artifact paths: ./output/ => output_content

Upon build artifacts are available at URL

Build Step: Command Line

Working directory

Allows starting a build in a subdirectory of the checkout directory (use a relative path).
When not specified, the build is started in the checkout directory.
All relative paths in TeamCity are relative to checkout directory.
If specified directory doesn't exist, TeamCity will create it (there is no need for mkdir to be used).

Agent Requirements

How to allow only those agents whose name starts with some specific string?

Add a new requirement with the following settings:

Parameter Name:
Condition: starts with
Value: <string>

How to allow only those agents which are running Linux?

Parameter Name: docker.server.osType
Condition: equals
Value: linux


Snapshot Dependencies

Snapshot dependencies are used to create build chains. When being a part of build chain the build of this configuration will start only when all dependencies are built. If necessary, the dependencies will be triggered automatically. Build configurations linked by a snapshot dependency can optionally use revisions synchronization to ensure the same snapshot of the sources.

Artifact Dependencies

Artifact dependency allows using artifacts produced by another build. 

Add new artifact dependency button opens a dialog where we can choose:

Depend on (string) - this is the name of the TeamCity build config which will be Artifacts source.

Get artifacts from:
  • Latest successful build
  • Latest pinned build
  • Latest finished build
  • Latest finished build with specified tag
  • Build from the same chain
  • Build with specified build number
Artifacts rules (string) - this is the pattern which defines which directory from artifacts to be copied to which directory in the local build. Provide here a newline-delimited set of rules in the form of
[+:|-:]SourcePath[!ArchivePath][=>DestinationPath]. Example:

ouptut => data/input/ 

ouptut is a directory from published artifacts from previous build and data/input/ is local path in the current build.

Dependencies can be temporary disabled which is useful when testing build configs.


Writing Build Steps

Writing bash scripts

To print some predefined property use:

echo teamcity.agent.home.dir = %teamcity.agent.home.dir%

In the output log we'll have e.g.:

teamcity.agent.home.dir = /home/agent-docker-01

If we have a build step which uses Command Line runner to run Custom script we can use variables in that script as:

echo MY_VAR value is: ${MY_VAR}

If we want to echo text which contains parentheses, we need to escape them:

echo Parentheses test: \(This text is between parentheses\)

If we want to find the id and name of the current user and group, we can use the following in the bash script:

echo user:group \(id\) = $(id -u):$(id -g)
echo user:group \(name\) = $(id -un):$(id -gn)

Log output is like:

user:group (id) = 1008:1008
user:group (name) = docker-slave-73:docker-slave-73
How to ping some remote server:

echo Pinging
ping -v -c 4

How to get current agent's public IP address?

Get agent\'s public IP address:
dig TXT +short

Running the build

If there are no compatible agents and you try to run the build, the following message appears:

Warning: No enabled compatible agents for this build configuration. Please register a build agent or tweak build configuration requirements.

TC automatically detects if there are any agents compatible with build steps (Build Steps item in the left-hand menu). They are shown in: 

Agent Requirements >> Agents Compatibility 
[In this section you can see which agents are compatible with the requirements and which are not.]

Integration with Artifacotry

TeamCity Artifactory Plug-in

Once plugin is installed and integrated, we can see Artifactory Integration section in build step settings. It contains the following settings:

  • Artifactory server URL (string)
  • Override default deployer credentials (boolean)
  • Publish build info (boolean)
  • Run license checks (boolean)
  • Download and upload by:
    • Specs
    • Legacy patterns (deprecated)
  • Download spec source:
    • Job configuration
    • File
  • Spec (string)
  • Upload spec source:
    • Job configuration
    • File
  • Spec (string)

Publish build info

If this is checked then Artifactory plugin creates and publishes on Artifactory server a json file which contains build info with the plain list of all artifacts. Path to this file on Artifactory is:

Artifact Repository Browser >> artifactory-build-info/<build_configuration_id>/xx-xxxxxxxxxxxxx.json

Build configuration id is usually in form ProjectName_BuildConfigurationName.

The content of that json file is like:

  "version" : "1.0.1",
  "name" : "My_Proj_Test",
  "number" : "25",
  "type" : "GENERIC",
  "buildAgent" : {
    "name" : "simpleRunner"
  "agent" : {
    "name" : "TeamCity",
    "version" : "2019.1.2 (build 66342)"
  "started" : "2019-08-19T10:47:12.557+0200",
  "durationMillis" : 112,
  "principal" : "Bojan Komazec",
  "artifactoryPrincipal" : "deployer",
  "artifactoryPluginVersion" : "2.8.0",
  "url" : "",
  "vcs" : [ ],
  "licenseControl" : {
    "runChecks" : false,
    "includePublishedArtifacts" : false,
    "autoDiscover" : true,
    "licenseViolationsRecipientsList" : "",
    "scopesList" : ""
  "modules" : [ {
    "id" : "My_Proj_Test :: 25",
    "artifacts" : [ {
      "type" : "",
      "sha1" : "b29930daa02406077d96a7b7a08ce282b3de6961",
      "sha256" : "47d741b6059c6d7e99be23ce46fb9ba099cfd6515de1ef7681f93479d25996a4",
      "md5" : "9b2bb321f2dd1a87857eb875ce22f7e1",
      "name" : "file1"
    }, {
      "type" : "",
      "sha1" : "b29930dda02406077d96a7b7a08ce282b3de6961",
      "sha256" : "47d741b6059c6d7e99be25ce46fb9ba099cfd6515de1ef7681f93479d25996a4",
      "md5" : "9b2bb321f5dd1a87857eb875ce22f7e1",
      "name" : "file2"
    } ]
  } ],
  "buildDependencies" : [ ],
  "governance" : {
    "blackDuckProperties" : {
      "runChecks" : false,
      "includePublishedArtifacts" : false,
      "autoCreateMissingComponentRequests" : false,
      "autoDiscardStaleComponentRequests" : false

Upload spec source with Job configuration

If we want to upload some output directory to Artifactory it is enough to set URL for Artifactory server, choose Job configuration as Upload spec source and set Spec as e.g.:

   "files": [
         "target": "path/to/output/",
         "flat": false

output is directory on TeamCity and path/to/output/ is path to the target directory on the Artifactory. In this example content in Artifactory will be at path*.

To avoid this, we can set working directory to ./output/ and then set pattern to "./". In that case the content would be at the path*.

It is possible to use TeamCity variables in Custom published artifacts value:


No comments: