Przejdź do treści

teamcity-configuration-as-a-code

TeamCity configuration for the Apollo/Logintegra servers, defined in Kotlin DSL (TeamCity versioned settings). The TeamCity server reads this repository and applies whatever it finds here - this repo is the source of truth, not the UI.

Layout

Everything lives under .teamcity/:

.teamcity/
  settings.kts            # entry point; pins DSL version, calls project(_self.Project)
  pom.xml                 # Maven build (Kotlin 2.0.21)
  _self/
    Project.kt            # root project: VCS roots, features, templates, subprojects
    buildTypes/           # reusable BuildType templates (Deploy*, Build*, Rebuild*, ...)
      automaticTests/     # templates for the Selenium/automat test pipeline
    constants/            # shared constant objects (see note below)
    enums/                # AppName, ServerGroup, TeamCityRequirement, TomcatAction
    utils/                # DSL extension functions (BuildExtensions.kt is the big one)
    vcsRoots/             # one object per Git repository
  logintegra/             # the actual projects, mirroring the TeamCity project tree
    apolloUniverse/       # test/demo tenants: common, oposy, wombaty, kapibary, qa, ...
    dedicated/            # per-customer builds (autochem, mediaExpert, pcc, ...)
    prod/                 # production deploys
    dev/ sandbox/ external/
  scripts/                # standalone .kts helpers used by build steps

Each project directory has a Project.kt holding the Project object, and a buildTypes/ subdirectory with one file per BuildType.

Working on it

cd .teamcity

# Type-check your changes (fast, works offline once dependencies are cached)
mvn compile

# Generate the XML that TeamCity will actually apply
mvn teamcity-configs:generate      # -> target/generated-configs/

generate needs network access to both download.jetbrains.com and the internal teamcity-apollo.logintegra.com DSL plugin repository.

Verifying a refactor changed nothing

The most useful safety net in this repo. Because the generated XML is the deployed configuration, a refactor that should be behaviour-neutral can be proven so by diffing generated output:

cd .teamcity
mvn teamcity-configs:generate && cp -r target/generated-configs /tmp/before
# ...make your changes...
mvn teamcity-configs:generate && diff -rq /tmp/before target/generated-configs

An empty diff means the TeamCity server will see no change at all.

Documentation

Conventions

  • Prefer a template in _self/buildTypes/ over copy-pasting a BuildType.
  • Prefer an extension function in _self/utils/ over inlining step/trigger config.
  • Never hardcode a host, port or credential in a BuildType - put it in _self/constants/ (servers belong in ServerConstants.SERVERS).
  • Prefer one parameterized BuildType with a server dropdown over one BuildType per host. Use selectBackendApp() from _self/utils/BuildParameterExtensions.kt, and reference the choice as %my.target.host% - this works inside reverse.dep.* values too. See RebuildDemoEnvironment for the worked example. A build that carries its own schedule trigger has to stay separate, because a trigger needs its parameters fixed at configuration time.
  • Build names and descriptions are user-facing in the TeamCity UI and are written in Polish; code, identifiers and comments-for-developers are in English.

Build-configuration limit

The server enforces a cap on the number of build configurations, and this repo has hit it (DEV-2539). Check the headroom before adding one:

grep -rh "^\s*buildType(" --include='*.kt' .teamcity | wc -l    # 107 as of this commit

Note the --include='*.kt': not every project file is called Project.kt (wombaty/apollo/ApolloProject.kt, wombaty/automaty/ApolloAutomaticProject.kt), so a grep restricted to Project.kt undercounts.

If you are out of slots, look for near-duplicate builds to collapse into a parameterized one before deleting anything.

Ostatnia zmiana: 2026-10-01 · kamil_szulc
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e