Templates & Meta-Runners

A build configuration template is a reusable "blueprint" for build configurations. When 10 microservices all need the same Maven build steps, failure conditions, and notification rules, define them once in a template — changes propagate automatically to all 10 configs.

Templates can define: build steps, triggers, failure conditions, artifact paths, agent requirements, build features, and parameters. Build configurations that use the template inherit all of these, with the option to override or extend each section.

Method 1: From an existing build configuration

1. Open the build config you want to use as a template.
2. Actions → Extract Template.
3. Give the template a name (e.g., Maven Java Microservice CI).
4. TeamCity creates the template and detaches the original config from it (it now references the template).

Method 2: Create from scratch

1. Administration → <Project> → Build configuration templates → Create build configuration template.
2. Configure build steps, triggers, parameters as usual.
3. In steps, use %param.name% for values that will vary per service (e.g., service name, Maven module path).

When creating a new build configuration

1. Administration → <Project> → Create build configuration.
2. Enter a name and ID.
3. In the Based on template field, select your template.
4. Click Create. The new config inherits all template settings.
5. Provide values for any template parameters (prompt parameters appear immediately).

Applying a template to an existing config

1. Open the build config: Administration → <Config> → General Settings.
2. In Based on template, select a template.
3. Save. Template settings are merged into the config. Conflicts are flagged.

Template parameters are placeholders that each build config fills in differently. Define them in the template with either a default value or a required-without-default specification.

# Template parameters (defined in the template itself):
service.name         = (empty, required — each config must provide this)
maven.module.path    = .           (default: root; override for multi-module)
maven.test.profile   = unit        (default: can override per config)
deploy.environment   = staging     (default: override for prod configs)

# In template build steps:
# Maven Goals:
#   -pl %maven.module.path% clean verify -P%maven.test.profile%
# Artifact paths:
#   %maven.module.path%/target/%service.name%-*.jar

To remove a build config from a template: Administration → <Config> → General Settings → Based on template → (none). The config retains a copy of all template settings at the time of detachment, but future template changes no longer propagate to it.

Use detach when: a service has diverged significantly from the standard build, or you're migrating away from an old template to a new one.

A meta-runner packages one or more build steps as a reusable custom runner type. Once created, it appears in the runner type dropdown alongside Maven, Gradle, etc. It's the best way to encapsulate a complex multi-command deploy procedure so teams can add it with two clicks.

Creating a meta-runner from existing steps

1. In a build configuration, configure the build steps you want to package.
2. Actions → Extract meta-runner.
3. Name the meta-runner (e.g., Deploy to Kubernetes) and give it an ID.
4. Identify parameters in the step scripts that should be exposed as meta-runner inputs (select them from dropdowns).
5. Save. The meta-runner XML is saved to <Data Dir>/config/projects/<ProjectId>/pluginData/metaRunners/.

Using a meta-runner

In any build config in the same project (or subproject): Add build step → select your custom runner from the list → fill in the exposed parameters.

Versioned settings synchronise all TeamCity project configuration (projects, build configs, templates, parameters, VCS roots) to/from a Git repository. Configuration is stored as Kotlin DSL — type-safe, IDE-friendly, and reviewable in GitHub pull requests.

Enabling versioned settings

1. Go to Administration → <Project> → Versioned Settings.
2. Select Synchronization enabled.
3. Choose a VCS Root (can be the same repo or a dedicated config repo).
4. Format: select Kotlin.
5. Click Apply. TeamCity immediately exports the current config to the repo as Kotlin DSL.

Example Kotlin DSL

// .teamcity/settings.kts
import jetbrains.buildServer.configs.kotlin.v2019_2.*
import jetbrains.buildServer.configs.kotlin.v2019_2.buildSteps.maven

project {
  buildType(Build)
  buildType(Test)
}

object Build : BuildType({
  name = "Build"
  vcs { root(MyRepo) }

  steps {
    maven {
      goals = "clean package -DskipTests"
      mavenVersion = defaultProvidedVersion()
    }
  }

  triggers {
    vcs { branchFilter = "+:refs/heads/*" }
  }

  artifactRules = "target/*.jar => artifacts"
})