Build Configurations & Build Steps

A build configuration (analogous to a Jenkins Job) is the central entity in TeamCity. It ties together: source code (VCS Root), what to do (Build Steps), when to do it (Triggers), success criteria (Failure Conditions), and what to save (Artifact Paths).

A runner is the type of work a build step performs. TeamCity ships with these built-in runners:

Key fields

Maven test reports

TeamCity automatically imports Surefire/Failsafe XML reports when using the Maven runner. No extra configuration needed. Test results appear in the Tests tab of the build. Failed tests are highlighted and show stack traces inline.

The most flexible runner — runs any executable or script. Two modes:

Executable with parameters

Executable: /usr/bin/python3
Parameters: scripts/deploy.py --env staging --version %build.number%

Custom script (inline)

#!/bin/bash
set -euo pipefail

echo "Build number: %build.number%"
echo "Branch: %teamcity.build.branch%"

# Run tests
npm install
npm test

# Package
npm run build
tar -czf dist-%build.number%.tar.gz dist/

# Example inline PowerShell step
param([string]$Env = "staging", [string]$Version = "0.0.0")

Write-Host "Deploying version $Version to $Env"
$ErrorActionPreference = "Stop"

# Run .NET build
dotnet build --configuration Release /p:Version=$Version

# Run tests
dotnet test --no-build --logger trx --results-directory TestResults

Write-Host "Build complete"

Each build step has an Execute step setting that controls when it runs:

Beyond a non-zero exit code, TeamCity can fail a build based on additional conditions:

Go to Build Configuration → Failure Conditions → Add failure condition to add conditions beyond the default.

Artifact paths tell TeamCity which files to publish after a build. Defined in General Settings → Artifact paths. Uses Ant-style patterns.

# Syntax: source_path [=> target_path]
# source_path: relative to checkout directory or working dir

# Publish a JAR
target/myapp-*.jar

# Publish to a named subdirectory in artifacts
target/myapp-*.jar => libs

# Publish test reports
target/surefire-reports/**/* => test-reports

# Publish entire dist directory
dist/** => release

# Publish multiple patterns (one per line)
target/myapp.jar
target/surefire-reports/**/*
*.log => build-logs

Accessing artifacts in the UI

After a build completes, go to the build's Artifacts tab to download files. Artifacts are also directly accessible via URL:

http://SERVER:8111/repository/download/BuildConfigId/.lastSuccessful/path/to/file.jar

The build number is the human-readable identifier for a build. Configured in General Settings → Build number format.

# Common build number patterns:

# Simple counter
{build.counter}
# Result: 42

# SemVer with counter
1.2.{build.counter}
# Result: 1.2.42

# Counter + Git SHA
{build.counter}.%build.vcs.number%
# Result: 42.a3f2c91

# Branch + counter (useful for feature branch builds)
%teamcity.build.branch%.{build.counter}
# Result: feature/login.5

Controls whether TeamCity wipes the agent's working directory before checking out source code.

Create a build configuration that compiles, tests, packages, and publishes a Java project artifact.

Runner: Maven
Goals: clean verify
Maven home: %teamcity.tool.maven.DEFAULT%
JVM options: -Xmx512m

Runner: Maven
Goals: package -DskipTests
Execute: Even if some previous steps failed
JVM options: -Xmx512m

Runner: Command Line
Script:
  echo "Build: %build.number%"
  echo "Branch: %teamcity.build.branch%"
  echo "Agent: %teamcity.agent.name%"
  ls -la target/*.jar 2>/dev/null || echo "No JAR produced"
Execute: Even if some previous steps failed

target/*.jar => artifacts
target/surefire-reports/**/* => test-reports