Phase 1: CI/CD Concepts & TeamCity Architecture — TeamCity 2017.2.2

1

What is CI/CD?

Before the era of CI, developers worked in long-lived branches for weeks or months, then merged everything at once — the dreaded "integration hell." CI/CD solves this by automating the feedback loop: every commit triggers a build and test run, so failures are discovered within minutes, not weeks.

Continuous Integration (CI)

Automatically build and test code on every commit. Goals:

Detect broken code within minutes of the commit
Keep the main branch always in a buildable, tested state
Reduce merge conflicts by integrating small changes frequently

Continuous Delivery (CD)

Extend CI so that a passing build automatically produces a deployable artifact — and optionally deploys it to staging or production. Goals:

Every green build is a release candidate
Deployment is a push-button (or fully automated) operation
Reduce release risk through smaller, more frequent releases

The feedback loop

Developer ──commit──▶ VCS (GitHub) ──webhook/poll──▶ TeamCity ──queue──▶ Build Agent ──compile──▶ ──test──▶ ──package──▶ ◀──result + artifacts── ◀──commit status (✓/✗)── Developer notified // within 2–5 min of commit

2

TeamCity in the CI Landscape

TeamCity is a commercial CI/CD server by JetBrains. It competes with Jenkins (open-source), CircleCI (cloud), GitLab CI (built-in), and GitHub Actions. Each has trade-offs:

Feature	TeamCity 2017.2	Jenkins	CircleCI	GitLab CI
Hosting	Self-hosted	Self-hosted	Cloud / self-hosted	Cloud / self-hosted
UI quality	Excellent	Dated (pre-Blue Ocean)	Good	Good
Build chain visualization	Built-in, visual	Plugin required	Workflow YAML	Pipeline YAML
Agent model	Pull-based agents	Push + pull	Docker containers	Runners
Config as code	Kotlin DSL (2017+)	Jenkinsfile (Groovy)	YAML	YAML
License	Free: 3 agents, 100 configs	Free / open-source	Paid tiers	Free tier + paid
Plugin ecosystem	Good (JetBrains-curated)	Huge (1800+ plugins)	Orbs	Built-in heavy
Best for	JVM teams, .NET teams	Any — highly flexible	Cloud-native teams	GitLab users

TEAMCITY FREE TIER

TeamCity Professional is free for up to 3 build agents and 100 build configurations. This is sufficient for most small-to-medium teams. Enterprise license removes these limits and adds advanced features (LDAP, 2FA, more agent types).

3

TeamCity Architecture

TeamCity has three distinct components that work together. Understanding this prevents configuration mistakes later.

TeamCity Server // Central brain — web UI, config, DB, queue │ HTTP :8111 │ HTTPS :443 (optional) │ ├──▶ Database // Build history, users, config (not artifacts) │ MySQL / PostgreSQL │ (or internal HSQL for dev) │ ├──▶ Data Directory // File system: plugins, logs, artifacts, config XML │ .BuildServer/ │ └──▶ Build Agents // Workers — run the actual build steps Agent 1 (local) Agent 2 (remote server) Agent N (Docker / cloud) // Agents connect TO server, not the other way

The Server

Runs as a Java web application (Tomcat-based). Responsibilities:

Hosts the web UI and REST API
Stores all project/build configuration
Manages the build queue — decides which agent gets which build
Collects and displays build results, test reports, artifacts
Sends notifications

The Database

Stores build history, user accounts, statistics, and runtime data. The project/build configuration is also mirrored here from XML files. Never share a database between two TeamCity servers.

The Data Directory

A file-system directory (default: ~/.BuildServer on Linux, %USERPROFILE%\.BuildServer on Windows). Contains:

config/ — project and build configuration XML files
system/artifacts/ — published build artifacts
system/caches/ — VCS caches, agent caches
logs/ — server and agent logs
plugins/ — installed plugins (.zip files)

Build Agents

Separate Java processes that run build steps. Key facts:

Agents connect outbound to the server — no inbound firewall rules needed for agents behind NAT
Each agent has a working directory where source code is checked out
An agent can only run one build at a time (by default)
Agents report their system properties (OS, JDK version, tools) to the server for compatibility matching

GOTCHA — Server vs Agent resources

The TeamCity server does not run build steps — it only orchestrates. Never install your build tools (Maven, Node, Docker) on the server machine alone and expect builds to work. Build tools must be installed on the agent machines.

4

Key Terms Glossary

These terms appear everywhere in TeamCity. Get them clear before proceeding.

Project

A container for related build configurations, VCS roots, and parameters. Projects can be nested (parent/child). Think of it as a "folder" for a team or application.

Build Configuration

The blueprint for a specific build — which source to use, what steps to run, what to do on failure, what artifacts to produce. Analogous to a Jenkins Job.

VCS Root

Connection to a version control repository (GitHub, GitLab, SVN, etc.). Defines URL, credentials, branch spec, and checkout rules. Shared across build configurations in a project.

Build Step

A single unit of work inside a build — run Maven, execute a shell script, run tests. A build configuration has one or more steps executed in order.

Runner

The type of build step — Maven Runner, Gradle Runner, Command Line Runner, PowerShell Runner, etc. Each runner has specific configuration fields.

Artifact

Files published after a successful build (JARs, WARs, ZIPs, reports). Defined by artifact path patterns. Stored on the server and available for download or use by dependency builds.

Trigger

The rule that starts a build automatically — on VCS commit, on a schedule, when another build finishes, or on retry. Without a trigger, builds only run when started manually.

Build Agent

The machine that actually runs the build steps. Has a working directory, installed tools, and system properties that TeamCity uses for compatibility matching.

Build Queue

Pending builds waiting for a compatible agent. TeamCity assigns builds from the queue to available agents based on requirements and agent pools.

Build Feature

An optional add-on to a build configuration — code coverage, commit status publishing, SSH agent, Docker login, etc. Applied on top of build steps without modifying them.

Snapshot Dependency

Ensures that build B uses the same source snapshot as build A. Forms a build chain — A must complete before B starts.

Artifact Dependency

Copies artifacts from one build configuration into another before the build starts. Used to pass compiled JARs, config files, or reports between stages.

5

TeamCity 2017.2.2 — Notable Features

Version 2017.2 (released November 2017) introduced several important features this tutorial covers in detail:

Feature	What it does	Covered in
Two-factor authentication	TOTP-based 2FA for all users	Phase 13
Pull Request build feature	Auto-detects and builds GitHub/Bitbucket PRs	Phase 5, Phase 10
Kotlin DSL versioned settings	Store all project config as Kotlin code in VCS	Phase 11, Phase 15
Composite build configurations	Fan-in/fan-out build chains with aggregated results	Phase 9
Docker support build feature	Docker login/logout, image cleanup after build	Phase 10
Improved REST API (v10)	New endpoints, better filtering, build chain API	Phase 14
Shared resources	Lock/semaphore for exclusive resource access	Phase 10

VERSION NOTE

The .2 in 2017.2.2 is a bugfix release. All major feature content in this tutorial applies to the full 2017.2.x line. The build number for 2017.2.2 is 51985. You can verify your version at Administration → Server Administration → Server Info.

6

Typical Commit-to-Artifact Workflow

This is the lifecycle of a single build, from the developer's commit to a published artifact:

1. Developer pushes commit ──▶ GitHub 2. GitHub fires webhook ──▶ TeamCity server (POST /app/rest/vcs-root-instances/checkingForChanges) or TeamCity polls VCS every N seconds (configured on VCS Root) 3. VCS trigger fires ──▶ Build added to the Build Queue 4. Agent becomes available ──▶ Server assigns build to agent 5. Agent checks out source ──▶ Working dir populated 6. Build steps execute Step 1: mvn compile Step 2: mvn test Step 3: mvn package 7. Artifact paths published ──▶ target/*.jar stored on server 8. Build result reported ──▶ UI updated (green/red) 9. Commit status published ──▶ GitHub PR shows ✓ or ✗ 10. Notifications sent ──▶ Email / Slack on failure

Total elapsed time from push to notification: typically 2–8 minutes for a Java project, depending on build duration and queue wait time.

7

Mental Model: Mapping a Build Script to TeamCity

If you have an existing build script, here's how its pieces map to TeamCity concepts:

In your script / workflow	TeamCity equivalent
`git clone https://github.com/org/repo`	VCS Root — defines the repo URL and credentials
`git checkout feature-branch`	Branch specification on the VCS Root
`export VERSION=1.2.3`	Environment variable parameter on build config
`mvn clean package`	Build step with Maven runner
`cp target/app.jar /artifacts/`	Artifact paths: `target/app.jar`
`if [ $? -ne 0 ]; then notify; fi`	Failure condition + notification rule
Cron job: run nightly at 02:00	Schedule trigger with cron expression
Run on every push to main	VCS trigger on branch `refs/heads/main`
Deploy only if tests pass	Snapshot dependency: Deploy config depends on Test config

KEY INSIGHT

TeamCity doesn't replace your build tool (Maven, Gradle, npm). It orchestrates them — triggering them at the right time, on the right machine, with the right parameters, and collecting their results. Your pom.xml or build.gradle stays exactly as is.

CI/CD Concepts & TeamCity Architecture