Jenkins to TeamCity Migration Guidelines

Overview

TeamCity offers a wide range of robust integrations and smart automation features to elevate your CI/CD workflows. However, migrating a complex, company-wide build farm is always a challenge. This guide outlines the migration process and highlights key similarities and differences between the two CI systems to support a smooth transition.

TeamCity vs Jenkins: Key Similarities and Differences

TeamCity and Jenkins are both popular CI/CD tools used for automating builds, testing, and deployments. While they share some core functionalities, there are also notable distinctions between the two.

Similarities

Both tools support pipelines as a way to structure build and deployment workflows (although they use slightly different terminology and approaches).
Both TeamCity and Jenkins are highly configurable and customizable through plugins or extensions.
Both tools support integration with container-based workflows, including Docker.

Differences

Configuration format. Jenkins uses declarative pipelines (Groovy-based files) or scripted pipelines (Jenkins DSL). With TeamCity, you always have a choice between configuring your build routines via UI, using Kotlin-based configuration scripts, or as a combination of both.
Hosting options. TeamCity offers both a self-hosted solution and a SaaS offering (through JetBrains-hosted cloud instances). Jenkins is exclusively self-hosted, requiring users to manage their own infrastructure.
Ease of setup and maintenance. TeamCity provides a more user-friendly setup process and a polished interface out of the box. Every configuration task — from setting up cloud agents to managing server nodes and clean-up rules — can be done directly through the TeamCity UI. You can also try TeamCity Pipelines for even more user-centric solution that lets you set up a build routine in just a few clicks. Jenkins typically requires more manual setup and configuration, and relies heavily on plugins, which may increase maintenance overhead.
Built-in features vs plugins. TeamCity includes built-in support for managing build agents, testing frameworks, code quality checks, and reporting tools. Jenkins’s functionality is heavily reliant on third-party plugins, which need to be selected and configured separately to achieve similar capabilities.
Integration with development tools. Because TeamCity is developed by JetBrains, it tightly integrates with their ecosystem of developer tools, such as IntelliJ IDEA and other JetBrains IDEs. Jenkins provides integrations with many tools but typically requires plugins or custom configurations for setting up these connections.
Cost. TeamCity's free tier limits the number of build agents and configurations, with additional costs for scaling up. Jenkins, being open-source, has no upfront costs, but hosting and plugin maintenance must be considered as operational expenses.

Planning the migration

Audit Your Jenkins Setup

Start by understanding everything that's currently running in Jenkins. This will help you avoid surprises and ensure feature parity in TeamCity.

Inventory all Jenkins jobs and pipelines
Export a full list of pipelines, whether scripted or declarative. Pay attention to naming conventions, folder structures, triggers, and branching strategies.
List all plugins in use
Use Matching Jenkins Plugins to TeamCity Features to generate a list. For each plugin, note its purpose and whether it has a counterpart in TeamCity (many features are built-in).
Document external integrations
Identify how Jenkins communicates with tools like artifact repositories (Artifactory, Nexus), container managers (Docker, Podman, Kubernetes), scret managers (Vault, AWS Secrets Manager), notification tools (Slack, email, MS Teams), infrastructure tools (Terraform, Ansible, etc.)
Review authentication and access control
Are you using SSO, LDAP, GitHub OAuth, or manual users? Document roles and permissions for migration to TeamCity’s user/group model.
Measure performance and resource usage
Collect metrics like build durations, queue times, and agent utilization. This gives you a baseline for comparing post-migration performance.

Prepare the TeamCity environment

Before starting the actual migration, make sure your TeamCity setup is ready.

Spin up a TeamCity instance Choose between TeamCity Cloud (fully managed by JetBrains) or TeamCity On-Premises (hosted and maintained by your team).
Provision Build Agents
TeamCity requires build agents to execute jobs. Decide whether you'll use:
- Self-hosted static agents (e.g., bare metal or VMs)
- Cloud-based agents (e.g., AWS, GCP, Azure)
- On-demand agents (with support for Docker/Kubernetes)
Connect your Version Control Systems
Add your repositories via VCS Roots. TeamCity supports GitHub / GitHub Enterprise, GitLab, Bitbucket Cloud, Server and Data Center, Bitbucket Cloud, Azure Repos, Perforce Helix, and other VCS providers via SSH/HTTP(S) protocols.
Learn the basics of TeamCity structure
TeamCity organizes work differently than Jenkins. Basic concepts include:
- Projects – the top-level container
- Build сonfigurations – similar to Jenkins jobs
- Templates – reusable build logic
- Build сhains – visualize and control dependencies
- Kotlin DSL – define build logic as code, versioned in Git Please refer to the Terminology Mapping and Feature Comparison part of this guide.
Set up secrets and credentials
Define secure parameters in TeamCity for API keys, tokens, and passwords. Map any Jenkins credentials to these.

Terminology Mapping and Feature Comparison

Before we begin, let's review how key Jenkins terms correspond to those in TeamCity.

Jenkins	TeamCity
Jenkins Master/Node	TeamCity server
Dumb Slave / Permanent Agent	Agent Pool
Executor	TeamCity Agent
View or Folder	Project
Job/Item/Project	Build configuration
Build	Build Steps
Pre Step	Build Step (partially) Bootstrap Step
Post\-build Action	Build step (partially) Deployers Deployment Build Configuration
Build Triggers	Build Triggers
Source Control Management (SCM)	VCS root
Workspace	Build Checkout Directory
Pipeline	Build Chain (via snapshot dependencies)
Label	Agent Requirements

The tiles below explain in greater detail how some of the key Jenkins concepts differ from their TeamCity counterparts.

Configuration files

Jenkins uses a Jenkinsfile, written in Groovy. It defines the pipeline steps in code.
TeamCity uses a Kotlin or XML settings file. TeamCity can automatically generate settings from a project configured in the UI, and you can edit it locally with full IDE support. Settings files can be stored either alongside the built project, or a completely separate remote repository.

Build definition

Jenkins jobs are either configured through the UI or defined in the Jenkinsfile as scripted or declarative pipelines.
Builds produced by build configurations, owned by parent projects. Each configuration can have multiple steps, triggers, parameters, and so on.

Variables

Jenkins variables are set through environment blocks or params {} inside the pipeline script. Can also be configured in the UI.
TeamCity uses parameters, defined per build configuration, project, or globally. These include environment variables passed to the agent's machine, and configuration parameters. Parameters can be shared with other configurations (output parameters) or configured to be private (input parameters).

Conditional steps

Jenkins supports conditional execution via when {} blocks in declarative pipelines or Groovy if in scripted ones.
TeamCity step conditions can be set in the UI or in Kotlin DSL. Supports a wide range of conditions: you can execute a step only when another step is successful, only if it fails, only if the specific parameter has a required value, and so on.

Artifact management

In Jenkins, you must explicitly declare what files to archive using archiveArtifacts.
You can use TeamCity UI, Kotlin DSL, or manually sent service messages to publish files produced during a build as an artifact. Artifact dependencies allow sharing published artifacts across various configurations.

Container managers

Jenkins supports Docker via the Docker Pipeline plugin or Kubernetes plugin, but you need to install and configure them.
TeamCity has built-in support for Docker and Podman, including Docker steps, agent images, and service containers. No plugins needed.

Build agents

Jenkins agents must be set up and connected manually (SSH, Docker, etc.). Agent templates via Kubernetes require plugin setup.
TeamCity supports cloud agents (JetBrains-hosted), Docker-based agents, and traditional self-hosted agents, with minimal config.

Parallel execution

Jenkins supports parallel blocks in scripted pipelines or parallel stages in declarative pipelines.
TeamCity can run builds or build steps in parallel, using build dependencies, splitting tests into batches, and agent-side parallelism.

Build logs

Jenkins outputs build results to console by default. You can enhance logs with timestamps and colors using plugins. Search and navigation are limited.
TeamCity offers real-time log streaming with timestamps and highlighting, server load metrics in Prometheus format, and archived history per build step. It’s possible to integrate TeamCity with 3rd party observability solutions like Dynatrace, Grafana, etc.

For a more detailed feature comparison between TeamCity and Jenkins, please refer to this document.

Matching Jenkins Plugins to TeamCity Features

Unlike Jenkins, where many core features rely on third-party plugins, TeamCity comes with most essential functionality — like Git and Docker support, test reporting, secrets management, and notifications — built in. This means fewer moving parts to maintain, no plugin compatibility issues during upgrades, and a more stable, out-of-the-box experience.

Here’s how some of Jenkins plugins match to the same built-in functionality in TeamCity.

Jenkins plugin	Equivalent TeamCity feature
Pipeline	Build configurations & Kotlin DSL
Blue Ocean	Build chains
Credentials plugin	Various parameters for different use cases: secrets stored on the TeamCity server, parameters of the "password" type, and remote parameters that retrieve sensitive data from external storages like HashiCorp Vault
Artifactory plugin	Built-in artifact storage and cloud/on-premises repository support. Support for S3 buckets and other cloud storage providers.
Git plugin	First-class Git support with deep VCS integrations (GitHub, GitLab, Bitbucket, Azure Repos, and more).
Docker plugin	Built-in Docker and Podman support: use Docker as build environment, pull services, build/push images
Slack notification plugin	Built-in notifications: Slack, email, Microsoft Teams, webhook- and service message-based notifications with customizable templates.
Kubernetes plugin	Various levels of built-in of Kubernetes integration: set up a Kubernetes cloud profile or use your cluster as an external executor processing TeamCity builds.
JUnit plugin	Native support for parsing JUnit test results, visual test reports, test history and flaky test detection.
HTML publisher plugin	Built-in support for publishing and viewing HTML build reports.
Throttle concurrent builds plugin	Smart queue prioritization, build limits per project/agent, and agent requirements logic.
AnsiColor plugin	Native log output with colored ANSI support and syntax highlighting in build logs
Timestamper plugin	TeamCity logs include structured timestamps, log folding, and filtering built-in
Workspace cleanup plugin	Built-in workspace and artifact cleanup rules with customizable retention policies.
Build timeout plugin	Flexible build timeout options (absolute, inactivity, custom logic) directly in build configuration settings.
Parameterized trigger plugin	Built-in snapshot and artifact dependencies trigger builds with specific parameters.

Migration Examples

In Jenkins, a job is a fundamental unit that defines a sequence of tasks. In TeamCity, this concept is represented by a build configuration. Each build configuration specifies a set of build steps, triggers, and other settings necessary to perform a build.

Jenkins defines build pipelines using a Jenkinsfile written in Groovy. This file typically lives in the root of your repository and describes the steps and stages of your build process.

Example 1. Basic pipeline configuration

Jenkins configuration:

pipeline {
agent any

    stages {
        stage('hello') {
            steps {
                echo "Hello World"
            }
        }
    }
}

In TeamCity, you can choose how to configure pipelines: via the UI or using the Kotlin DSL. Some benefits of using the Kotlin DSL for pipeline configuration include:

Human-readability and maintainability
Version control: Store configurations in any supported VCS for better traceability
Extensibility: Supports loops, conditionals, and reusable components. Think a fully-fledged programming language rather than just a markup like XML, XAML, or YAML, which means custom data classes, custom libraries, and so on.
UI synchronization: Changes made in the UI can be reflected in the DSL and vice versa.

If you proceed with the Kotlin DSL for configuration, instead of a single file, your setup lives in a remote directory (by default, the hidden .teamcity folder in the repository root) and is written in type-safe Kotlin code. This makes it easier to catch errors early and leverage IDE features like code completion.

Here’s the equivalent setup to the previously described Jenkins file in TeamCity Kotlin DSL:

import jetbrains.buildServer.configs.kotlin.*

project {
    buildType(HelloBuild)
}

object HelloBuild : BuildType({
    name = "Hello Build"

    steps {
        script {
            name = "Say Hello"
            scriptContent = "echo Hello World"
        }
    }
})

This Kotlin code defines a project with a single build configuration that runs a script printing Hello World. TeamCity automatically picks up this configuration when connected to your repo.

Example 2: Simple build job

Jenkins:

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }
    }
}

In TeamCity, you can use the all-purpose command-line step to perform regular building actions, or specialized build steps tailored to interact with specific build tools: .NET, Maven, Python, Gradle, and more.

TeamCity Kotlin DSL (CLI step):

import jetbrains.buildServer.configs.kotlin.*

project {
    buildType(SimpleBuild)
}

object SimpleBuild : BuildType({
    name = "Simple Build"

    steps {
        script {
            name = "Maven Build"
            scriptContent = "mvn clean package"
        }
    }
})

Via the TeamCity UI (Maven step):

Create a build configuration.
Add a Maven build step.
Set the Goal property of a Maven step to clean package.

Example 3: Running tests

Jenkins:

pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                sh 'pytest tests/'
            }
        }
    }
}

TeamCity Kotlin DSL:

import jetbrains.buildServer.configs.kotlin.*

project {
    buildType(RunTests)
}

object RunTests : BuildType({
    name = "Run Tests"

    steps {
        script {
            name = "Run Pytest"
            scriptContent = "pytest tests/"
        }
    }

    requirements {
        contains("teamcity.agent.jvm.os.name", "Linux") // Optional: adjust based on your environment
    }
})

TeamCity UI:

Create a build configuration.
Add a build step of a command-line or Python type.
Specify the pytest tests/ step script.

Example 4: Deploying to production

Jenkins:

pipeline {
    agent any
    stages {
        stage('Deploy') {
            steps {
                sh 'kubectl apply -f deployment.yaml'
            }
        }
    }
}

TeamCity Kotlin DSL:

import jetbrains.buildServer.configs.kotlin.*

project {
    buildType(DeployToProduction)
}

object DeployToProduction : BuildType({
    name = "Deploy to Production"

    steps {
        script {
            name = "Apply Kubernetes Deployment"
            scriptContent = "kubectl apply -f deployment.yaml"
        }
    }

    requirements {
        contains("teamcity.agent.jvm.os.name", "Linux") // Adjust if needed
    }
})

Via the TeamCity UI:

Create a deployment configuration.
Add a CLI build step.
Set the kubectl apply -f deployment.yaml command.

Triggers

Both Jenkins and TeamCity support build triggers to automate the initiation of builds. In Jenkins, triggers like cron, pollSCM, and GitHub webhook triggers are commonly used.

In TeamCity, various triggers are available to provide similar automation.

VCS trigger: the build is triggered when changes are detected in the version control system roots attached to the build configuration.
GitHub Checks Webhook Trigger: the build is triggered for every single commit pushed to the source GitHub repository. In addition, posts detailed build result info on a GitHub page without a Commit Status Publisher configured.
Schedule trigger: the build is triggered at a specified time.
Finish build trigger: the build is triggered after a build of the selected configuration is finished.
Maven artifact dependency trigger: the build is triggered if there is a content modification of the specified Maven artifact which is detected by the checksum change.
Maven snapshot dependency trigger: the build is triggered if there is a modification of the snapshot dependency content in the remote repository which is detected by the checksum change.
Retry build trigger: the build is triggered if the last build failed or failed to start.
Branch remote run trigger: personal build is triggered automatically each time TeamCity detects new changes in particular branches of the VCS roots of the build configuration. Supports Git and Mercurial.
NuGet dependency trigger: starts a build if there is a NuGet package update detected in the NuGet repository.
Perforce shelve trigger: starts a build on a change in shelved Perforce files.

By leveraging these triggers, you can ensure efficient automation in your CI/CD workflow, reducing manual intervention and improving deployment speed.

Environment variables

Jenkins allows defining environment variables within the environment block. In TeamCity, environment variables are managed as build parameters that can be defined at the project or build configuration level.

Jenkins:

pipeline {
   environment {
      API_KEY = 'my_secret_key'
   }
   stages {
      stage('Build') {
         steps {
            echo "Using API Key: ${API_KEY}"
         }
      }
   }
}

TeamCity Kotlin DSL:

import jetbrains.buildServer.configs.kotlin.*

project {
    buildType(UseApiKey)
}

object UseApiKey : BuildType({
    name = "Use API Key"

    params {
        password("API_KEY", "credentialsJSON:*****") // Replace with your actual secure credential reference
    }

    steps {
        script {
            name = "Echo API Key"
            scriptContent = "echo 'Using API Key: %API_KEY%'"
        }
    }
})

Equivalent in the TeamCity UI:

Open build configuration or project settings and create a parameter named env.API_KEY.
Specify a parameter value.
Reference it in a build step or configuration settings via the %env.API_KEY% syntax.

Post-build actions

In Jenkins, post-build actions are defined in the post section and include tasks such as notifications, archiving artifacts, or triggering other builds.

In TeamCity, similar functionality can be achieved using Build Features or additional Build Steps configured to execute based on success or failure conditions.

Artifacts configured when you set up a VCS connection, inside a VCS root. Run your build at least once, and you'll be able to use the file/folder browser to easily select produced files that should be published as artifacts
Notifications are set up on the per-build configuration basis
Delivery tasks are performed by the Deployment configurations and Deployers

Conclusion

Migrating from Jenkins to TeamCity offers greater efficiency, enhanced automation, and reduced dependency on plugins. We hope that this guide can serve as a good starting point in helping you to migrate from Jenkins to TeamCity.

10 September 2025