TeamCity Setup and Usage Guide with FOSSA Integration

About

TeamCity is a continuous integration and delivery (CI/CD) server by JetBrains, known for its powerful build toolset and broad language support. It automates software builds, tests, and deployments, and provides real-time feedback on build status. Key features include:

Build Pipelines & Configurations: Define complex workflows with multiple sequential or parallel steps, conditional steps, and dependencies (e.g., build chains). These are organized as Build Configurations within projects.
Build Agents: Dedicated worker processes that execute build jobs. Agents can run on diverse platforms (Windows, Linux, macOS) and allow TeamCity to run builds in parallel across an elastic build grid.
VCS Integration: First-class integration with Git, GitHub, GitLab, Bitbucket, and other version control systems. TeamCity monitors repositories for changes and can trigger builds on each commit.
Extensive Tool Support: Out-of-the-box runners for Maven, Gradle, .NET, Docker, and more, plus a flexible command-line runner for custom scripts. Plugins provide additional integrations (e.g., Slack notifications, issue trackers).
Real-Time Monitoring: Web UI to watch live build logs, test results, and code coverage. TeamCity streams test reports and build progress as the agent runs the steps.
Artifacts and Reports: Built-in artifact storage for build outputs (e.g. binaries, packages) and test report integration (JUnit, NUnit, etc.). Build artifacts are saved to the server for download or use in downstream builds.

TeamCity is available in two modes: Self-Hosted (On-Premises) and TeamCity Cloud. Both offer the same core CI/CD capabilities, but TeamCity Cloud is a managed SaaS service where JetBrains hosts the server (on AWS) and provides build agents out-of-the-box. Self-hosted TeamCity gives you full control over the server and environment, with the trade-off of managing the server infrastructure yourself.

In a typical TeamCity workflow, the server detects a new commit in the VCS and records the change in its database. A configured VCS Trigger then queues a new build for that change. The build is picked up from the queue by an available build agent, which executes the defined build steps. As the agent runs the build, it reports progress, logs, and test results back to the TeamCity server in real time. Once the build finishes, the agent uploads any configured artifacts (build outputs) to the server for storage and distribution. This process is illustrated below:

Figure: Basic CI flow with TeamCity – the server queues builds triggered by VCS changes and assigns them to agents; agents run the build steps and report results and artifacts back to the server.

flowchart LR
Developer((Developer)) -->|Push code| VCS[(Git Repository)]
TeamCityServer[TeamCity Server] -- detects change --> VCS
TeamCityServer -- queues build --> BuildAgent[Build Agent]
BuildAgent -- checks out code --> VCS
BuildAgent -- runs build and tests --> BuildAgent
BuildAgent -- reports status --> TeamCityServer
BuildAgent -- uploads artifacts --> TeamCityServer
TeamCityServer -- stores data --> DB[(Build Database & Artifacts)]
Developer <-- reviews results --> TeamCityServer

Setup Guide

Self-Hosted TeamCity Installation (On-Premises)

To install TeamCity on your own server, ensure the following prerequisites:

A supported OS: Windows, Linux, or macOS (64-bit). Java is required to run the TeamCity server (the Windows installer bundles a compatible JRE; on Linux/macOS you need Java 8 or 11 installed).
Sufficient resources: At least 4 CPU cores and 4GB+ RAM recommended for a small team setup (larger installations may require 16GB or more for dozens of concurrent builds).
Database: TeamCity comes with an internal database for evaluation. For production, use an external SQL database (e.g. PostgreSQL, MySQL) to store build history and metadata.

Installation steps:

Download TeamCity: Grab the latest TeamCity release from the official download page. Choose the installer for your platform (Windows .exe or cross-platform .tar.gz archive).
Run Installer / Unpack Archive: On Windows, run the installer and follow the setup wizard. On Linux/Mac, extract the TeamCity<version>.tar.gz to a desired install directory. This includes TeamCity Server and a build agent.
Start the Server: If installed as a Windows Service, start the "TeamCity Server" service from the Services console (the installer may start it automatically). Otherwise, launch TeamCity manually:
- Windows: Open a Command Prompt in the TeamCity\bin directory and run:
```
.\runAll.bat start
```
- Linux/Mac: In the <TeamCity>/bin directory, run:
```
./runAll.sh start
```
This runAll script starts the TeamCity web server and one default build agent on the local machine. By default, the web UI will be available at http://localhost:8111 (8111 is the default HTTP port).
Initial Configuration: Open the TeamCity URL in a browser. On first launch, you'll be guided through a setup wizard:
- Data Directory: Confirm or change the location for TeamCity's Data Directory, which stores configuration and build results.
- Database Setup: Choose the internal database for a quick start (HSQLDB) or connect an external database. For now, you can proceed with the default internal DB (you can migrate to an external DB later for production use).
- License Agreement: Accept the license terms to continue.
- Admin Account: Create the administrator user by specifying a username and password. After these steps, the TeamCity server finishes its configuration and is ready to use. You can log in with the admin account you created and start creating projects and build configurations.
Additional Build Agents (optional): The default installation provides one local agent. To run more parallel builds, set up extra agents on other machines or containers. TeamCity provides a separate agent package or Docker image. For example, to run a TeamCity agent in Docker and connect it to your server:
```
docker run -d --name teamcity-agent \
  -e SERVER_URL="http://<your-server-host>:8111" \
  jetbrains/teamcity-agent
```
Replace <your-server-host> with the TeamCity server URL. Agents will auto-register with the server and appear in the Agents section of the UI, where an admin can authorize them to start building. Each build agent runs in its own process and can run one build at a time; adding agents increases your parallel build capacity.

Note: TeamCity's free Professional license (default) supports up to 100 build configurations and 3 concurrent build agents. For larger needs, consider purchasing additional agent licenses or an Enterprise license.

For more detailed installation instructions, refer to the official TeamCity installation guide.

TeamCity Cloud Setup (Managed SaaS)

Setting up TeamCity Cloud is significantly faster, as JetBrains manages the server installation and infrastructure for you. Follow these steps to get started with TeamCity Cloud:

Sign Up: Go to the TeamCity Cloud sign-up page and register for an account. Upon registration, TeamCity Cloud will provision a dedicated TeamCity server instance for you (hosted on AWS).
Initial Access: Within minutes, you'll receive an invitation email with a link to your TeamCity Cloud instance. Click the link to open your TeamCity Cloud portal and set up your administrator credentials (if prompted). The server is pre-configured and running the latest TeamCity version.
Hosted Build Agents: TeamCity Cloud comes with JetBrains-hosted build agents ready to use. By default, cloud instances provide a pool of Windows and Linux agents that spin up on demand for your builds. You don't need to install any agents to start – the cloud will auto-allocate agents when you run builds. (The usage limits or build credits depend on your subscription.)
Create Your Project: Using the TeamCity Cloud web UI, create a new project and attach your VCS repository (e.g., a GitHub repo). TeamCity Cloud will guide you through setting up a VCS connection and a build configuration for your project. You can then run the first build to ensure everything is working.

TeamCity Cloud provides nearly the same experience as on-prem, with a few differences and limitations to be aware of:

Server administration options are limited (since JetBrains manages the server). For example, you cannot install custom plugins or directly edit server configuration files.
Some plugins and features that require low-level server access (e.g., certain authentication methods like Windows domain auth, or deprecated VCS like CVS) are not available in Cloud.
The system is kept up-to-date by JetBrains, and data backups/clean-ups are handled automatically. You don't need to worry about upgrades or maintenance tasks.
TeamCity Cloud still allows bring-your-own build agents if needed. You can install a self-hosted agent and connect it to your cloud instance (for example, to run builds on specialized hardware or on an internal network). JetBrains provides an authentication token mechanism to securely connect external agents to your cloud server.

Overall, TeamCity Cloud is a convenient managed solution: you get a full-featured CI/CD platform without maintaining the server. If you require more control or integration with on-prem resources, the self-hosted option is available with full flexibility. For a detailed comparison, see the official TeamCity Cloud documentation.

Ongoing Usage

Build Configurations and Projects

In TeamCity, all build definitions live inside Projects. A Project is a logical container for related build configurations, templates, and settings. Within each project, you define one or more Build Configurations, each of which represents a CI/CD pipeline or workflow for your software. A build configuration includes:

VCS Roots: Links to your source code repositories (e.g., a Git repository URL, credentials, and branch settings). This tells TeamCity where to fetch the code. A VCS root can be shared by multiple build configurations in the project.
Build Steps: A sequential list of tasks to execute on the agent. Each step can use a predefined runner (Maven, Gradle, .NET, Docker, etc.) or a custom script. For example, a build configuration might have steps like "Install dependencies", "Run tests", "Build artifacts", etc. You can reorder steps and enable/disable them as needed.
Build Triggers: Conditions that automatically start a new build. The most common trigger is the VCS Trigger, which kicks off a build whenever new commits are detected in the repository. You can also schedule builds (e.g., nightly) or set up other trigger types.
Parameters: Configurable values (environment variables or configuration parameters) that can be used in build scripts. Parameters can be defined at the project or build level to avoid hard-coding values.
Artifact Rules: Definitions of which files or directories from the build should be saved as artifacts. For example, after a successful build you might archive target/*.jar or build/output/** as artifacts. These artifacts will be uploaded by the agent to the server and stored, making them available for download or for use in dependent builds.
Build Features and Integrations: Optional settings like test result reporting, code coverage analysis, notifications, etc. For instance, a build feature can parse JUnit test reports so TeamCity can show test failures and history in the UI.

When setting up a new project, TeamCity's UI can autodetect some of these settings. For example, if you point TeamCity to a GitHub repository, it can auto-create a VCS root and suggest a build step (via the Auto-detect build steps function) based on the repository contents (e.g., detect a Maven project). You can refine the build configuration in the Project Settings UI, which provides sections for VCS settings, build steps, triggers, failure conditions, and more. All changes are saved versioned in TeamCity's database (and can be stored as code in a Kotlin DSL, if desired, for config-as-code).

It's useful to utilize templates for build configurations if you have many projects with similar steps. A build configuration template can define common steps or settings, which projects can inherit and then override as needed. This DRY approach simplifies managing large numbers of builds. Projects can also be hierarchically organized (a parent project can share settings with subprojects).

For more information on configuring build configurations, see the TeamCity build configuration documentation.

Build Agents and Parallel Execution

Build agents are the workers that run your builds. TeamCity employs a client-server architecture: the TeamCity Server coordinates builds, but agents do the actual work of executing build steps on some machine or container. Key points about build agents:

Single Build at a Time: Each agent can run one build configuration at a time. The number of active build agents therefore limits your parallel build capacity. For example, with 3 agents you can have up to 3 builds running simultaneously (across all projects).
Agent Pools: In on-prem TeamCity, you can group agents into pools and assign projects to pools. This is useful for reserving agents for certain teams or workloads. In TeamCity Cloud, the concept is similar but JetBrains-hosted agents are automatically managed.
Compatibility: An agent can be configured with certain environment capabilities (like a JDK version, specific tools installed, OS type, etc.). TeamCity matches build configurations to compatible agents based on requirements. For instance, you can mark a build step to run only on agents with the "Linux" environment, or require a minimum Java version; TeamCity will then queue the build until a suitable agent is free.
Agent Authorization: When a new agent connects to the TeamCity Server, it appears in the Agents list as unauthorized by default (for security). An administrator needs to authorize it in the UI, after which TeamCity can use it to run builds. (The exception is the default agent on the same machine as the server, which is auto-authorized.)
Scaling Agents: You can dynamically scale agents. On self-hosted, you might start/stop VM instances with agents or use cloud integration plugins (TeamCity has a feature to start cloud instances for agents on demand). In TeamCity Cloud, the hosted agents scale automatically within the limits of your plan, and you can also attach self-hosted agents for additional capacity.

Monitoring agents is done via the Agents tab in the UI, which shows each agent's status (Idle, Building, Disconnected, etc.), the last build run, and any enabled/disabled flags. Agents can be disabled temporarily (e.g., for maintenance) via the UI – a disabled agent will not accept new builds. You can also view an agent's environment details and compatible configurations from this page. Keeping agents updated is straightforward: agents automatically upgrade themselves when the server is upgraded, ensuring version compatibility.

Learn more about agent configuration in the TeamCity build agent documentation.

Version Control Integration (GitHub, GitLab, etc.)

TeamCity's integration with version control systems (VCS) is central to its CI workflow. A VCS Root in TeamCity defines how to connect to a repository – including the repo URL, authentication (password, SSH key, token), and what branches to monitor. Once a VCS root is attached to a build configuration, the TeamCity server will monitor the repository for changes. By default, the server polls for new commits every 60 seconds, but you can adjust this interval or configure a VCS webhook for immediate notifications.

For popular services like GitHub, GitLab, and Bitbucket, TeamCity can integrate via their APIs: for example, TeamCity Cloud will preconfigure a GitHub.com connection if you sign in via GitHub OAuth. This simplifies setup of VCS roots (credentials are handled by the connection). You can also use repository-specific features: TeamCity can merge pull requests, label builds in VCS, and report build status back to Git hosting (so you see CI status checks on your pull requests).

GitHub Integration Example: To connect a GitHub repo, you would create a VCS root in TeamCity with: VCS type "Git", the repository URL (HTTPS or SSH), and authentication (personal access token or SSH key). Once the VCS root is set and attached to a build configuration, you can add a VCS Trigger so that any commit to a specified branch (e.g., main or any branch with a certain pattern) triggers a new build. You might also set up GitHub webhooks (via GitHub repository settings or using TeamCity's "Webhooks" feature) so that GitHub notifies TeamCity instantly on a push event, rather than waiting for polling. This results in faster build starts and reduces load from polling.

TeamCity supports multiple VCS roots per build configuration as well, in case your build needs to pull from multiple repositories (e.g., perhaps a submodule or a dependent library from another repo). It also supports labeling sources, so you can have TeamCity tag the VCS with the build number/revision on successful builds, etc. All these settings are configurable in the VCS Root and Build Features sections of the project settings.

For comprehensive information on VCS integration, see the TeamCity VCS root configuration guide.

In summary, integrating with VCS is usually one of the first steps in using TeamCity: you connect your repo, set up a trigger, and TeamCity will take care of the rest by automatically checking out the code on agents and keeping track of what revision was built in each build record. The tight VCS integration ensures traceability of which commits are included in every build.

Managing Build Artifacts and Test Reports

One of the advantages of TeamCity is the handling of build outputs and test results as first-class citizens in the CI process.

Artifacts: For each build configuration, you can specify artifact rules to tell TeamCity which files to preserve after the build finishes. For example, a Java project might produce target/myapp.jar – by adding an artifact rule like:

target/myapp.jar => myapp.jar

TeamCity will archive myapp.jar and store it on the server. These artifacts are accessible via the web UI on the build results page, or via direct HTTP URLs for automation. You can also set up artifact dependencies, where one build configuration pulls artifacts from another (ensuring, for instance, that a deployment build uses the exact artifact produced by an earlier build). TeamCity handles artifact storage cleanup based on retention policies (e.g., keep last N builds' artifacts) which you can configure globally or per project. In TeamCity Cloud, artifact storage is managed for you (with some limits), whereas on-prem you can configure the storage location or even use external artifact storage if needed.

Test Reporting: TeamCity surfaces test results prominently. As the agent runs tests, it reports test progress to the server. You can see in real-time which tests are running, passed, or failed. TeamCity supports many testing frameworks natively. For instance, if you use the Maven or Gradle build runner, it will automatically parse Surefire and other test reports. You can also add a Build Feature for parsing custom reports (like JUnit XML, NUnit, etc.) if your build uses a command-line step to run tests. The Tests tab for a build shows all detected tests, with statistics like duration, and highlights new failures. TeamCity also maintains a history of tests so it can mark tests as "flaky" or identify when a test started failing. This helps with tracking test reliability over time.

Build Logs: Every build has a complete log that is accessible from the UI or downloadable as text. The log includes step-by-step output of your build steps, along with timestamps. TeamCity annotates the log with useful markers (e.g., block start/finish for each build step, and highlighting errors). This makes it easier to navigate large logs. Searching within logs is supported via the web UI.

Build Results and Statuses: The build result page in TeamCity aggregates all relevant info: VCS revision, list of changes (commits) included in the build, artifacts, test results, code coverage (if configured), any build metrics or statistics (like code inspection results, if integrated), and agent used. You can also see execution time and agent-specific details. If a build fails, TeamCity can pinpoint which changes might have caused it (via the "Investigate" feature) and notify responsible engineers.

TeamCity's robust artifact and report management ensures that each build not only compiles your code but also produces deliverables and insights (tests, coverage, etc.) that are readily accessible. This makes it easy to use TeamCity as a one-stop solution for continuous integration feedback.

Using with FOSSA

FOSSA is an open source management tool that can be integrated into TeamCity to automate license compliance and security vulnerability scanning as part of your CI pipeline. By integrating FOSSA into TeamCity, you can generate a Software Bill of Materials (SBOM) for each build and catch any license or security issues early, without manual effort. Below is a guide on setting up FOSSA in your TeamCity builds and leveraging it for continuous compliance.

Integrating FOSSA into TeamCity Builds

TeamCity does not have a built-in FOSSA plugin, but integration is straightforward using FOSSA's CLI tool. The high-level approach is: obtain the FOSSA CLI, run it during the build to scan the project, and use its output to fail the build if issues are found. Here's how to set it up:

Install FOSSA CLI (in build step): FOSSA provides an open-source CLI (fossa-cli) that scans your code for dependencies and licenses. Rather than installing this manually on all agents, you can add a TeamCity build step that downloads the CLI on the fly. For example, add a new Build Step of type "Command Line". Set the step name (e.g., "FOSSA Scan") and choose Custom script as the execution mode. In the script, insert the following commands:
```
# Download and install FOSSA CLI
curl -H "Cache-Control: no-cache" https://raw.githubusercontent.com/fossas/fossa-cli/master/install-latest.sh | bash
# Run FOSSA analysis
fossa analyze
```
This sequence will fetch the latest fossa binary and then execute fossa analyze against your repository. The fossa analyze command scans the project's dependencies and sends data to the FOSSA service for analysis. Ensure your build agent has internet access to retrieve the script and connect to FOSSA's servers. (If your environment is offline, you might pre-install the CLI and use offline scanning, but the online approach is the simplest.)

Configuration: It's best to run this FOSSA step after your build has compiled or fetched dependencies. For instance, if your build step uses Maven/Gradle/npm to download dependencies, place the FOSSA step after those, so that all project dependencies are in place for FOSSA to detect. You may also run fossa init once to generate a baseline .fossa.yml config if needed, but in many cases fossa analyze auto-detects the project structure.

Figure: Adding a FOSSA scan step in TeamCity using a Command Line runner. The custom script downloads the fossa-cli and runs fossa analyze on the codebase.
Provide FOSSA API Key: The FOSSA CLI needs an API token to upload scan results to your FOSSA account. You should create an API key in your FOSSA account (in FOSSA's Integration Settings or API Tokens section) and then supply it to the build. The recommended way is to add it as a secret parameter in TeamCity rather than hard-coding it in the script. Go to the build configuration's Parameters section and add a new parameter: set the Kind to "Environment variable", name it for example env.FOSSA_API_KEY, and paste your API token as the value. Mark it as secret (so it's hidden in logs). This will make the API key available in the build agent's environment as FOSSA_API_KEY. The fossa analyze command will automatically pick up this env var for authentication.
Fail Build on Policy Violations (optional): By default, fossa analyze will always exit 0 (it won't fail the TeamCity build even if it finds license or vulnerability issues). To enforce policy compliance, you can add a follow-up step to evaluate the FOSSA scan results. FOSSA CLI provides a fossa test command for this purpose. Add another Command Line build step (e.g., "FOSSA Policy Check") after the analyze step, with the script:
```
fossa test
```
This command will poll FOSSA for the scan status and exit with a non-zero code if any issues are found that violate your defined policies. Essentially, fossa test waits for the analysis to complete in FOSSA's backend, then: if the project has license violations or high-severity vulnerabilities (as per policies), it will cause the TeamCity step to fail (thus marking the whole build failed); if all is clear or only allowed issues exist, it exits 0 and the build can proceed. We recommend configuring this step with "Execute step: If all previous steps finished successfully" so it only runs if the build and scan completed successfully (as shown in the figure below). You can also specify a timeout (default 600s) for fossa test if your scans typically take a while.

The outcome is that any licensing or security problems detected by FOSSA will automatically break the build, bringing immediate attention to the issue. Developers can then consult the detailed FOSSA report for that build.

(No output is produced in this step when passing; on failure, fossa test will output the issues that caused the failure directly in the TeamCity log for visibility.)

For more information on integrating FOSSA with TeamCity, visit the FOSSA TeamCity documentation.

With these steps in place, every TeamCity build will trigger a FOSSA scan. Ensure that your FOSSA project is set up (you may need to log in to FOSSA's web app to adjust license policies or review initial scan results). FOSSA will scan all dependencies (including transitive ones) and generate an SBOM and license compliance report for the project. The integration we configured uses the API key to tie scans to your FOSSA account/project, where you can review the SBOM, license findings, and any flagged issues.

Continuous SBOM Generation and License Compliance in CI/CD

Once FOSSA is integrated, every TeamCity build produces an up-to-date inventory of open-source components and their licenses. This automated SBOM generation and review process yields several benefits for the CI/CD pipeline:

Continuous License Compliance: FOSSA will detect if any dependency in the build carries a license that conflicts with your organization's policies (for example, copyleft licenses or unapproved licenses). By running on each build, compliance is checked continuously, not just at release time. Any introduction of a problematic license is caught immediately, and the build can be failed to prevent progression. This shifts license checks left into development, reducing legal risk.
Security Vulnerability Visibility: Along with license scanning, FOSSA can track known vulnerabilities in dependencies (via integration with vulnerability databases). Each build's SBOM can be checked against vulnerability data, alerting you to high-risk components. This means you get alerts for new vulnerabilities in your dependencies as they appear, tied to the specific build that introduced or contains them. Early detection allows developers to upgrade or patch before a release.
Complete Dependency Audit Trail: The SBOM produced by FOSSA gives a full list of open source components in your software, down to each transitive library and their licenses. TeamCity can store this as an artifact or link to the FOSSA report, creating an audit trail for every build. In regulated industries or for compliance audits, you can show exactly what went into a build and prove that all licenses were accounted for.
Developer Efficiency and Confidence: Automating these checks means developers don't have to manually audit licenses or run separate tools. The CI pipeline enforces compliance automatically, which increases developer velocity. They get rapid feedback if something is wrong (e.g., adding a new library that brings in GPL-licensed code), and can fix it in the normal development workflow. Legitimate changes sail through, since approved licenses won't fail the build.
Integration with TeamCity Workflow: FOSSA results can be integrated with TeamCity's UI and notifications. A failed build due to FOSSA will show up just like any other failure, with logs pointing to the cause. This ensures that open-source risk management is part of your existing CI feedback loop, not a separate silo.

Overall, incorporating FOSSA into TeamCity transforms open source compliance from a periodic or ad-hoc task into a continuous process. It provides an accurate, real-time inventory of third-party components in each build and highlights issues immediately, without slowing down the CI/CD pipeline. By catching license or security problems early (on every commit/build), your team can remediate them long before release, avoiding last-minute surprises. This continuous compliance approach hardens your software supply chain against both legal and security risks while maintaining development agility. FOSSA's integration ensures that every code change is automatically vetted for open source concerns as an integral part of your TeamCity CI workflow, giving you peace of mind that your project remains compliant and secure with every build.

For more information on FOSSA's continuous compliance capabilities, visit the FOSSA Continuous Compliance page.