# 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

- [Building Docker images and deploying from the registry](<https://bitbucket.org/logintegraspzoo/teamcity-configuration-as-a-code/src/main/docs/docker-registry.md>)

## 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](<https://youtrack.logintegra.com/issue/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.
