TeamCity

https://www.jetbrains.com/help/teamcity
Admin
TeamCity is a CI/CD solution by JetBrains that automates build, test, and deployment processes for...
Tokens:544,183
Snippets:8,885
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install wget

Source: https://www.jetbrains.com/help/teamcity/install-teamcity-server-on-linux-or-macos.html

Install the wget utility for downloading files.

```bash
root@ubuntu:/# apt update && apt install wget -y
```

--------------------------------

### Install on Linux distributions

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-get-started.html

Manual installation commands for Debian/Ubuntu, RHEL/Fedora, and Arch Linux.

```bash
curl -fsSLO https://github.com/JetBrains/teamcity-cli/releases/latest/download/teamcity_linux_amd64.deb
sudo dpkg -i teamcity_linux_amd64.deb
```

```bash
sudo rpm -i https://github.com/JetBrains/teamcity-cli/releases/latest/download/teamcity_linux_amd64.rpm
```

```bash
curl -fsSLO https://github.com/JetBrains/teamcity-cli/releases/latest/download/teamcity_linux_amd64.pkg.tar.zst
sudo pacman -U teamcity_linux_amd64.pkg.tar.zst
```

--------------------------------

### Install on Windows

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-get-started.html

Installation methods for Windows using Winget, PowerShell, CMD, Chocolatey, or Scoop.

```powershell
winget install JetBrains.TeamCityCLI
```

```powershell
irm https://jb.gg/tc/install.ps1 | iex
```

```cmd
curl -fsSL https://jb.gg/tc/install.cmd -o install.cmd && install.cmd && del install.cmd
```

```powershell
choco install teamcitycli
```

```powershell
scoop bucket add jetbrains https://github.com/JetBrains/scoop-utils
scoop install teamcity
```

--------------------------------

### Install Java JDK

Source: https://www.jetbrains.com/help/teamcity/install-teamcity-server-on-linux-or-macos.html

Install Amazon Corretto 21 and verify the installation.

```bash
root@ubuntu:/opt# apt install java-common -y
root@ubuntu:/opt# wget https://corretto.aws/downloads/latest/amazon-corretto-21-x64-linux-jdk.deb
root@ubuntu:/opt# dpkg --install amazon-corretto-21-x64-linux-jdk.deb
# verify the installation
root@ubuntu:/opt# java -version
openjdk version "21.0.18" 2025-01-17 LTS
OpenJDK Runtime Environment Corretto-21.0.18.10.1 (build 21.0.18+10-LTS)
OpenJDK 64-Bit Server VM Corretto-21.0.18.10.1 (build 21.0.18+10-LTS, mixed mode)
```

--------------------------------

### Verify installation

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-get-started.html

Check that the CLI is correctly installed and accessible.

```bash
teamcity --version
```

--------------------------------

### Quick Start Commands

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli.html

Common commands for authenticating, listing builds, starting jobs, and checking the queue.

```bash
# Authenticate with your TeamCity server
teamcity auth login

# List recent builds
teamcity run list --limit 10

# Start a build and watch it run
teamcity run start MyProject_Build --branch main --watch

# View logs from the latest build of a job
teamcity run log --job MyProject_Build

# Check what's in the queue
teamcity queue list
```

--------------------------------

### Install via shell script

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-get-started.html

Automatically detect OS and architecture to install the binary to your PATH.

```bash
curl -fsSL https://jb.gg/tc/install | bash
```

--------------------------------

### Start TeamCity server

Source: https://www.jetbrains.com/help/teamcity/install-teamcity-server-on-linux-or-macos.html

Execute the runAll script to start the server and the bundled build agent.

```bash
teamcity@ubuntu:/opt$ TeamCity/bin/runAll.sh start
Spawning TeamCity restarter in separate process
TeamCity restarter running with PID 2817
Starting TeamCity build agent...
Java executable is found: '/usr/lib/jvm/java-21-amazon-corretto/bin/java'
Starting TeamCity Build Agent Launcher...
Agent home directory is /opt/TeamCity/buildAgent
Done [3230], see log at /opt/TeamCity/buildAgent/logs/teamcity-agent.log
```

--------------------------------

### Install TeamCity CLI on Windows

Source: https://www.jetbrains.com/help/teamcity/ai-agent-integration.html

Installation commands for Windows using Winget or PowerShell.

```powershell
winget install JetBrains.TeamCityCLI
```

```powershell
irm https://jb.gg/tc/install.ps1 | iex
```

--------------------------------

### Wildcard Pattern Matching Examples

Source: https://www.jetbrains.com/help/teamcity/cloud/wildcards.html

Examples showing how specific Ant-style patterns match files within the sample directory structure.

```text
a
├── b
│   ├── c
│   │   └── file1.txt
│   ├── file2.txt
│   └── file3.log
├── d
│   └── file4.log
└── file5.log
```

```text
a
├── b
│   └── file3.log
├── d
│   └── file4.log
└── file5.log
```

```text
a
└── b
    ├── c
    │   └── file1.txt
    ├── file2.txt
    └── file3.log
```

```text
a
└── b
    ├── file2.txt
    └── file3.log
```

```text
a
└── b
    ├── c
    │   └── file1.txt
    ├── file2.txt
    └── file3.log
```

--------------------------------

### teamcity project cloud image start

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-managing-cloud-agents.html

Starts a new cloud instance from a selected image.

```APIDOC
## teamcity project cloud image start

### Description
Starts a new cloud instance from a selected image. Returns the new instance ID on success.

### Parameters
- **image_id** (string) - Required - The ID or name of the image to start
- **--json** (flag) - Optional - Output as JSON
```

--------------------------------

### Example of Multiple VCS Checkout Rules

Source: https://www.jetbrains.com/help/teamcity/cloud/vcs-checkout-rules.html

A practical example demonstrating exclusion and specific mapping rules for a project structure.

```text
-:src/help
+:src=>production/sources
+:src/samples=>./samples
```

--------------------------------

### Shell alias examples with external tools

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-aliases.html

Examples of aliases integrating external tools like notify-send or jq.

```bash
teamcity alias set watchnotify '!teamcity run watch $1 && notify-send "Build $1 done"'
teamcity alias set faillog     '!teamcity run list --status=failure --json | jq ".[].id"'
```

--------------------------------

### Install Gems via Command Line

Source: https://www.jetbrains.com/help/teamcity/cloud/ruby-environment-configurator.html

Use this script in a Command Line build step to install necessary gems before executing other build tasks.

```bash
gem install rake --no-ri --no-rdoc
gem install bundler --no-ri --no-rdoc
```

--------------------------------

### JDK environment variable formats

Source: https://www.jetbrains.com/help/teamcity/upgrade-notes.html

Examples of the new and legacy environment variable formats for Java versions.

```text
env.JDK_<major>_<minor>[_x64]
```

```text
env.JDK_1_6
```

```text
env.JDK_1_7
```

```text
env.JDK_1_8
```

```text
env.JDK_11_0_x64
```

```text
env.JDK_1_4
```

```text
env.JDK_14_0
```

```text
env.JDK_16
```

```text
env.JDK_18
```

--------------------------------

### VCS Repository Error Log

Source: https://www.jetbrains.com/help/teamcity/upgrade-notes.html

Example of the error output generated when the teamcity.TruncateIgnoreReasonConverter.copyReasons property encounters a version mismatch in TFS.

```text
Error
  collecting changes
 for
  VCS repository
 ...


 Failed
  to collect TFS changes
 -

 From
  version x
 is
  greater
 then
  current version y
```

--------------------------------

### Obtain CSRF token for REST API

Source: https://www.jetbrains.com/help/teamcity/upgrade-notes.html

Retrieve a CSRF token via a GET request to include in subsequent write operations.

```http
GET https://your-server/authenticationTest.html?csrf
```

--------------------------------

### Start Cloud Instance

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-managing-cloud-agents.html

Provision a new cloud instance from a specified image.

```bash
teamcity project cloud image start ubuntu-22-large
teamcity project cloud image start ubuntu-22-large --json
```

--------------------------------

### Windows Service Management Scripts

Source: https://www.jetbrains.com/help/teamcity/cloud/start-teamcity-agent.html

Batch scripts for installing, starting, and stopping the TeamCity agent service.

```batch
<agent home>\bin\service.install.bat
```

```batch
<agent home>/bin/service.start.bat
```

```batch
<agent home>/bin/service.stop.bat
```

--------------------------------

### Build from source

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-get-started.html

Advanced installation methods using Go or cloning the repository.

```bash
go install github.com/JetBrains/teamcity-cli/tc@latest
```

```bash
git clone https://github.com/JetBrains/teamcity-cli.git
cd teamcity-cli
go build -o teamcity ./tc
```

--------------------------------

### Install TeamCity CLI on macOS and Linux

Source: https://www.jetbrains.com/help/teamcity/ai-agent-integration.html

Installation commands for macOS and Linux using Homebrew or the provided install script.

```bash
brew install jetbrains/utils/teamcity
```

```bash
curl -fsSL https://jb.gg/tc/install | bash
```

--------------------------------

### Example configuration file structure

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-configuration.html

A sample YAML configuration file showing server definitions and command aliases.

```yaml
default_server: https://teamcity.example.com
servers:
  https://teamcity.example.com:
    user: alice
  https://teamcity-staging.example.com:
    user: alice
    guest: true
  https://teamcity-prod.example.com:
    user: alice
    ro: true
aliases:
  rl: 'run list'
  rw: 'run view $1 --web'
  mine: 'run list --user=@me'
```

--------------------------------

### Configure buildAgent.properties file

Source: https://www.jetbrains.com/help/teamcity/cloud/configure-agent-installation.html

Example configuration file defining server URL, agent name, directory paths, and authorization token.

```properties
## The address of the TeamCity server. The same as is used to open the TeamCity web interface in the browser.
## Must include the protocol specification (https:// is recommended).
serverUrl=http://localhost:8111/

## The unique name of the agent used to identify this agent on the TeamCity server
## Use blank name to let server generate it.
## By default, this name would be created from the build agent's host name
name=Default agent

## Container directory to create default checkout directories for the build configurations.
workDir=../work

## Container directory for the temporary directories.
## Please note that the directory may be cleaned between the builds.
tempDir=../temp

## Container directory for agent state files and caches.
## TeamCity agent assumes ownership of the directory and can delete the content inside.
systemDir=../system


######################################
#   Optional Agent Properties        #
######################################
## A token which is used to identify this agent on the TeamCity server for agent authorization purposes.
## It is automatically generated and saved back on the first agent connection to the server.
authorizationToken=1234567890abcdefghijklml
```

--------------------------------

### Pattern Example

Source: https://www.jetbrains.com/help/teamcity/cloud/duplicates-finder-java.html

Example configuration for include and exclude patterns.

```text
+:testData/tables/**
-:testData/**
-:testdata/**
-:[testData]/**
```

--------------------------------

### Configure JVM command line parameters

Source: https://www.jetbrains.com/help/teamcity/cloud/simple-build-tool-scala.html

Example of setting maximum and initial heap size for the JVM running the build.

```text
-Xmx512m -Xms256m
```

--------------------------------

### Install via npm

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-get-started.html

Cross-platform installation using the Node Package Manager.

```bash
npm install -g @jetbrains/teamcity-cli
```

--------------------------------

### Specify Solution File Path

Source: https://www.jetbrains.com/help/teamcity/cloud/visual-studio-sln.html

Example path format for the solution file relative to the Build Checkout Directory.

```text
vs-addin\addin\addin.sln
```

--------------------------------

### Install a Ruby Gem

Source: https://www.jetbrains.com/help/teamcity/cloud/rake.html

Command to install a specific Ruby gem on a build agent.

```bash
gem install <gem_name>
```

--------------------------------

### Quick shortcut examples

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-aliases.html

Commonly used shortcuts for basic navigation and listing commands.

```bash
teamcity alias set rl       'run list'
teamcity alias set rv       'run view $1'
teamcity alias set rw       'run view $1 --web'
teamcity alias set jl       'job list'
teamcity alias set ql       'queue list'
```

--------------------------------

### Install TeamCity CLI

Source: https://www.jetbrains.com/help/teamcity/cloud/ai-agent-integration.html

Installation commands for TeamCity CLI on macOS, Linux, and Windows.

```bash
brew install jetbrains/utils/teamcity
```

```bash
curl -fsSL https://jb.gg/tc/install | bash
```

```powershell
winget install JetBrains.TeamCityCLI
```

```powershell
irm https://jb.gg/tc/install.ps1 | iex
```

--------------------------------

### Migrate .NET CLI build steps

Source: https://www.jetbrains.com/help/teamcity/cloud/upgrading-dsl.html

Compare the legacy parameter-based configuration with the modern, explicit build step syntax.

```kotlin
steps {
    step {
        type = "dotnet"
        param("dotnet-command", "build")
        param("dotnet-paths", "WindowsAzure.sln")
    }
}
```

```kotlin
steps {
    dotnetBuild {
        projects = "WindowsAzure.sln"
    }
}
```

--------------------------------

### Download Build Log via URL

Source: https://www.jetbrains.com/help/teamcity/build-log.html

Example URL for downloading a build log for a specific build ID.

```text
http://localhost:8111/downloadBuildLog.html?buildId=4102
```

--------------------------------

### Install skill at project level

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-ai-agent-integration.html

Installs the skill specifically for the current project instead of globally.

```bash
teamcity skill install --project
```

--------------------------------

### Install skill for specific agents

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-ai-agent-integration.html

Targets one or more specific AI agents for skill installation.

```bash
teamcity skill install --agent claude-code
teamcity skill install --agent claude-code --agent cursor
```

--------------------------------

### View Agent Configuration Help

Source: https://www.jetbrains.com/help/teamcity/cloud/configure-agent-installation.html

Display the help menu for the agent configuration command to see available parameters.

```bash
./agent.sh configure --help
Java executable is found: '/Library/Java/JavaVirtualMachines/amazon-corretto-11.jdk/Contents/Home/bin/java'
Configuring TeamCity build agent...
TeamCity Agent configurator
Usage:
	configure PROPERTIES_FILE
	configure -f PROPERTIES_FILE
	configure [PROPERTIES]
	configure --usage
	status
	status short
Where PROPERTIES format is --key=value or --key value
Supported properties:
	* --agent-config-file=PATH - path to build agent properties file (<Agent Root>/conf/buildAgent.properties by default)
	* All default properties that can be configured in buildAgent.properties file
	  Also there are aliases for some of them:
		auth-token = authorizationToken
		logs-dir = logsDir
		name = name
		server-url = serverUrl
		system-dir = systemDir
		temp-dir = tempDir
		work-dir = workDir
```

--------------------------------

### Magic Keyword Query Examples

Source: https://www.jetbrains.com/help/teamcity/search.html

Examples of using magic keywords to filter builds by state.

```text
configuration:nightly project:Mega $pinned
c:nigh p:mega $pin
M::night $pin
```

--------------------------------

### Define Build Steps in Kotlin DSL and YAML

Source: https://www.jetbrains.com/help/teamcity/cloud/configuring-build-steps.html

Examples of configuring a two-step build process using Kotlin DSL and YAML formats.

```kotlin
import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.maven
import jetbrains.buildServer.configs.kotlin.buildSteps.script

object SampleConfig: BuildType({
    name = "Sample two-step configuration"
    steps {
        script {
            name = "Step 1"
            id = "simpleRunner"
            scriptContent = """echo "Hello world""""
        }
        maven {
            name = "Step 2"
            id = "Step_2"
            goals = "clean package"
            jdkHome = "%env.JDK_21_0_ARM64%"
            mavenVersion = custom {
                path = "%teamcity.tool.maven.3.8.6%"
            }
        }
    }
})
```

```yaml
Job1:
    name: Sample two-step job
    steps:
      - type: script
        name: Step 1
        script-content: echo "Hello world"
      - type: maven
        name: Step 2
        pom-location: pom.xml
        goals: clean package
        jdk-home: '%env.JDK_21_0_ARM64%'
        maven-version:
          bundled_3_8: {}
```

--------------------------------

### Configure application.properties

Source: https://www.jetbrains.com/help/teamcity/artifacts-migration-tool.html

Sample configuration for the migration tool including the server host and authentication token.

```properties
teamcity.storage.migration.access.token=aBcEfgHIjkLMnoPQRsTUVwxyz
teamcity.storage.migration.host=http://localhost:8111
```

--------------------------------

### Distinguish Types Example

Source: https://www.jetbrains.com/help/teamcity/cloud/duplicates-finder-java.html

Example code used to demonstrate the impact of the 'Distinguish types' setting.

```java
new MyIDE().updateStatus()
```
Tokens:
Raw