TeamCity CI: Getting Started

By Kokil Thapa | Last reviewed: September 2026

Your team picked JetBrains TeamCity because builds need to be fast, visible, and dependable. TeamCity CI: Getting Started is where most teams stall: the UI looks friendly, yet the first green build still feels far away. I've maintained GitLab CI and Deployer pipelines on production Laravel apps for years. TeamCity solves a different problem—deep build history, reusable templates, and first-class .NET and PHP tooling in one server. This guide walks you from blank server to a working pipeline with real commands, config snippets, and the mistakes I see on client projects that treat CI as an afterthought. For broader pipeline context, see our Laravel GitLab CI step-by-step guide.

How Do You Get Started with TeamCity CI?

TeamCity is a self-hosted CI server from JetBrains. You run a central server and one or more build agents. The server stores configuration, queues jobs, and serves the web UI. Agents execute builds on machines you control—on-prem VMs, cloud instances, or Docker containers.

The onboarding path has four milestones. Each one should produce a visible result before you move on.

1. Install the TeamCity server and open the web UI on port 8111.
2. Register a build agent on the same host or a separate machine.
3. Create a project, attach a Git VCS root, and add build steps.
4. Run the first build, inspect logs, then add tests and deploy hooks.

Do not wire production deploy on day one. Get checkout, dependency install, and unit tests green first. That matches how I roll out CI on custom Laravel applications: prove the build, then add gates.

What Hardware and Software Do You Need Before Installing TeamCity?

TeamCity runs on Linux, Windows, or macOS. For production Laravel CI, Ubuntu 22.04 or 24.04 on a VPS is the path I recommend. It matches the stacks described in our Linux system administration service and keeps PHP versions predictable.

Server sizing for small teams

A team of five to fifteen developers can start with 2 vCPU, 4 GB RAM, and 40 GB SSD for the TeamCity server alone. Build agents need separate resources—at least 2 vCPU and 4 GB RAM per agent running PHP 8.3+ and Composer 2.10. Shared hosting will not work; you need shell access and outbound Git access.

Software prerequisites on the agent

• PHP 8.3 or 8.4 (Laravel 12 needs PHP 8.2+; Laravel 13 needs PHP 8.3+)
• Composer 2.10
• Git 2.x
• Node.js 26 LTS if you compile front-end assets with Vite 8.x
• MySQL 8.4 or PostgreSQL 18 client libraries for integration tests

Install TeamCity using the official tarball or Docker image from JetBrains TeamCity installation documentation. Docker is fine for evaluation. Production teams often prefer a managed VM with persistent data and logs directories on separate volumes.

Quick Linux install via tarball

# On Ubuntu 24.04 — download current TeamCity server bundle from JetBrains
sudo mkdir -p /opt/teamcity /var/teamcity
cd /opt/teamcity
sudo tar xzf TeamCity-*.tar.gz --strip-components=1

# Run under a dedicated user
sudo useradd -r -s /bin/false teamcity
sudo chown -R teamcity:teamcity /opt/teamcity /var/teamcity

# systemd unit (simplified)
sudo tee /etc/systemd/system/teamcity.service <<'EOF'
[Unit]
Description=TeamCity Server
After=network.target

[Service]
User=teamcity
ExecStart=/opt/teamcity/bin/teamcity-server.sh run
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now teamcity

Open http://your-server:8111, accept the licence, and create the admin account. The first-run wizard also installs a bundled agent on the same machine—useful for smoke tests, not for heavy parallel builds.

How Do You Create Your First TeamCity Build Pipeline?

TeamCity organises work into projects and build configurations. A project maps to a product or repo. A build configuration is one pipeline—main CI, release, or nightly.

Step 1: Create the project and VCS root

In the UI, choose Create Project → From a repository URL. Paste your Git HTTPS or SSH URL. TeamCity probes branches and suggests a default. For SSH, upload a deploy key under Administration → SSH Keys.

Set checkout rules explicitly. A common Laravel rule checks out the default branch plus pull-request refs if you add a feature-branch build later:

# VCS checkout rule example in TeamCity UI
+:refs/heads/*
-:refs/heads/dependabot/**

Step 2: Add build steps

For a Laravel 12 app, define these build steps in order:

1. Command Line — composer install --no-interaction --prefer-dist --optimize-autoloader
2. Command Line — cp .env.ci .env && php artisan key:generate
3. Command Line — php artisan migrate --force --env=testing (when a test DB is available)
4. Command Line — php artisan test --parallel or vendor/bin/pest
5. Command Line — npm ci && npm run build (optional artefact step)

Mark step 1–4 as required. Fail fast on Composer lock drift—never use composer update in CI.

Step 3: Configure triggers and parameters

Add a VCS Trigger so every push to main queues a build. Define system properties the agent resolves at runtime:

# Build parameters (Name → Value)
env.PHP_BIN=/usr/bin/php8.3
env.COMPOSER_MEMORY_LIMIT=512M
teamcity.build.checkoutDir=%system.teamcity.build.checkoutDir%

Use Snapshot dependencies when one configuration must consume artefacts from another—for example, a package build that feeds a deploy build. That pattern mirrors artefact promotion in blue-green deployment pipelines.

How Do You Connect TeamCity to Git and Run Laravel Builds?

Version control integration is where TeamCity earns its keep. The server polls or receives webhooks, maps commits to configurations, and shows a per-commit status graph you can share with stakeholders.

Webhook vs polling

Prefer webhooks for GitLab or GitHub. Polling adds delay and load. In GitLab, add a webhook pointing to:

https://teamcity.example.com/app/hooks/github

TeamCity documents provider-specific URLs in the VCS hosting integration guide. Use a read-only deploy token scoped to the single repository.

Agent-friendly Laravel CI script

Keep a .teamcity/ci.sh script in the repo so local runs match CI:

#!/usr/bin/env bash
set -euo pipefail

export APP_ENV=testing
export DB_CONNECTION=sqlite
export DB_DATABASE=":memory:"

composer install --no-interaction --prefer-dist
php artisan config:clear
php artisan test --parallel

Point the TeamCity step to bash .teamcity/ci.sh. Developers on macOS or WSL can run the same file before push. Validate JSON env files with our JSON formatter tool when generating CI secrets payloads.

Build chains on real projects

On booking platforms like Adventure Third Pole Trek, CI must run migrations, feature tests, and sometimes asset builds. Split heavy suites across configurations: fast-check on every push, full-suite nightly. Use parallel test runs with ParaTest inside the agent to cut wall-clock time.

Enable the XML report processing build feature for PHPUnit JUnit output:

php artisan test --log-junit build/report.xml

TeamCity surfaces failed tests in the Overview tab. That beats scrolling raw console logs when a suite has hundreds of cases.

TeamCity CI vs GitLab CI vs Jenkins: Which Should You Pick?

Teams often compare TeamCity against tools they already run. The right choice depends on hosting model, language mix, and who maintains the server.

If your organisation already lives in GitLab, read our GitHub Actions vs GitLab CI comparison before adding another server. TeamCity shines when builds are complex, multi-platform, or you need granular test history without gluing plugins together.

How Do You Harden TeamCity with Caches, Secrets, and Quality Gates?

A green hello-world build is not production CI. The next layer prevents slow pipelines, leaked tokens, and silent regressions.

Dependency caching

Add a shared cache directory on the agent for Composer and npm. TeamCity cache rules key off composer.lock and package-lock.json hashes. See build caching strategies to speed up CI for key naming patterns that also work in TeamCity cache configs.

# Example cache path on Linux agent
/home/teamcity/.cache/composer
/home/teamcity/.cache/npm

Secrets management

Never store production DB passwords in plain build parameters. Use TeamCity project-level parameters marked Password, or connect HashiCorp Vault / AWS Secrets Manager via integrations. Rotate deploy keys quarterly. Our secrets in CI/CD pipelines guide applies directly—mask values in logs and scope tokens per environment.

Quality gates

Add build failure conditions:

• Test count must not drop compared to last successful build.
• Code coverage must not fall below a threshold (see code coverage gates in CI).
• Static analysis step with zero new blocker issues.

Wire SonarQube or PHPStan as a dedicated step. Fail the build on regression, not on legacy debt you have not scheduled yet.

Kotlin DSL for configuration as code

Export project settings to a .teamcity/ directory in your repository. Commit Kotlin DSL so changes go through review:

// Simplified Kotlin DSL — buildType block
object MainCi : BuildType({
    id("MyProject_MainCi")
    name = "Main CI"
    vcs {
        root(MyProject_HttpsGit)
    }
    steps {
        script {
            name = "Run tests"
            scriptContent = "bash .teamcity/ci.sh"
        }
    }
    triggers {
        vcs {
            branchFilter = "+:refs/heads/main"
        }
    }
})

Kotlin DSL is the escape hatch when click-ops drift appears. It pairs well with the verification patterns in build verification and quality gates.

For agent isolation guidance, follow self-hosted CI runner security practices. TeamCity agents face the same SSH-key and supply-chain risks as GitLab runners or Jenkins nodes.

Deploy step (after CI is stable)

Only after tests and gates pass should you add deploy. On VPS targets I still use Deployer 7 from a final step:

composer install --no-dev --optimize-autoloader
vendor/bin/dep deploy production --branch=main

That mirrors the flow in deploy Laravel with GitLab CI to a VPS, swapped into a TeamCity script step. Sister legal-tech sites on shared EC2—such as Notary Kathmandu—benefit from identical deploy scripts regardless of CI front-end.

If you evaluate Azure DevOps alongside JetBrains, compare with Azure Pipelines first pipeline guide. For Jenkins-heavy estates, our Jenkins CI/CD tutorial shows equivalent stages.

Database migration safety belongs in CI discussion too. Run migrations against disposable schemas in CI, never production. Read database migrations in CI/CD pipelines before automating schema changes on deploy.

Static analysis fits cleanly as a pre-test step. Integrate the workflow from static code analysis in CI with SonarQube when stakeholders want trend lines, not one-off lint runs.

When pipelines grow noisy, add secrets scanning with Gitleaks as an early build step. It catches accidental .env commits before tests even start.

For Pest-based suites, align reporting with Laravel testing with Pest in CI/CD. The JUnit exporter works the same under TeamCity.

Ongoing maintenance—agent OS patches, PHP minor upgrades, disk monitoring—maps to support and maintenance services if your team lacks dedicated ops headcount.

Test regex-heavy validation rules locally with the regex tester before encoding them in CI scripts.

Learn more about my background on the about me page, or browse the full project portfolio for Laravel systems that run automated pipelines in production.

Key Takeaways

• Install TeamCity server, register a dedicated agent with PHP 8.3+ and Composer 2.10, then prove checkout and tests before adding deploy.
• Model each pipeline as a build configuration with explicit VCS rules, shell steps, and JUnit report processing for PHPUnit or Pest.
• Use webhooks instead of polling, keep a shared .teamcity/ci.sh, and split fast vs nightly builds as test suites grow.
• Add Composer/npm caches, masked password parameters, and coverage or test-count gates before calling the pipeline production-ready.
• Export Kotlin DSL to Git when UI changes accumulate—treat CI config like application code.
• TeamCity CI: Getting Started is complete only when agents are patched, secrets rotated, and deploy steps idempotent on rollback.

People Also Ask

Is TeamCity free for small teams?

JetBrains offers a free licence for up to 100 build configurations and three build agents. That covers many Laravel products until you add multiple environments, platforms, or long build matrices. Beyond those limits you need a commercial licence keyed to agent count.

Can TeamCity build pull requests from GitLab or GitHub?

Yes. Add a VCS root, enable branch specifications for merge-request or pull-request refs, and attach a VCS trigger with a branch filter. TeamCity posts commit status back to the provider when you configure a connection and use the REST API or bundled integration.

Does TeamCity replace Deployer or GitLab CI for Laravel deploys?

No. TeamCity orchestrates when builds and deploys run. Deployer, Envoy, or shell scripts still perform the release on your VPS or cloud host. Many teams keep GitLab for source hosting and add TeamCity when they outgrow simple YAML pipelines or need richer test analytics.

How do you speed up slow TeamCity PHP builds?

Cache Composer and npm directories on agents, run tests in parallel with ParaTest, use snapshot dependencies instead of rebuilding artefacts, and pin agents to PHP versions so opcache stays warm between runs. Disable Xdebug unless a dedicated coverage configuration needs it.

Ship Your First TeamCity Pipeline with Confidence

TeamCity CI: Getting Started boils down to a reliable agent, a reproducible shell script, and gates that fail loudly. Install the server, wire Git, run Laravel tests, then layer caches and secrets before you touch production. The payoff is faster feedback and a build history your whole team can trust.

Need help standing up TeamCity agents beside an existing Laravel app, or migrating from Jenkins without downtime? Contact us to plan the pipeline, harden runners, and connect deploy steps that match how your team actually ships.