Migrate from TeamCity to Jenkins

Migrate from TeamCity to Jenkins: what the move involves

If your TeamCity renewal, licensing terms or data residency rules are pushing you toward Jenkins, plan for a rebuild rather than a file copy. Jenkins does not read TeamCity build configurations, so each pipeline must be re-expressed as a Jenkinsfile committed to the project's source repository, with build history, artifacts, parameters and secrets handled as a separate handoff. Jenkins is distributed under the MIT License, so the server itself carries no per-agent or per-seat license fee; the cost sits in infrastructure, staff time and plugin upkeep. Your existing TeamCity versioned settings, if you enabled them, are the most useful starting point because they give you a committed inventory of every project, build configuration and template to work from. In most organizations the work is done by the platform or DevOps engineers who own the TeamCity server, with input from the application teams who know which builds are critical. Security staff should be involved early, because CI secrets generally cannot be exported from TeamCity in readable form, so each credential has to be re-entered in Jenkins, ideally through a credentials store, and rotated where its value cannot be confirmed. Build artifacts and logs also need an export plan, since they are not carried over automatically. The effort and risk depend mostly on the number of build configurations, how many use build chains or snapshot dependencies, and how much Windows or licensed tooling your agents rely on. Ask any implementation partner for a written inventory and a per-project scope before agreeing a timeline.

Before cutting over, run both systems in parallel for the projects you care most about, and confirm each Jenkins pipeline produces the same artifacts and test results as its TeamCity counterpart. Check agent requirements at this stage: TeamCity agent capabilities should map to Jenkins agent labels, so jobs land on machines that have the right toolchain. Confirm with your own engineers which Jenkins plugins you need and which Java version your controller will run, using the Jenkins support policy as the reference. Plan the controller and agent layout using the Jenkins scaling guidance, which recommends keeping the controller focused on coordination, with work pushed to dedicated build agents and all configuration, plugins and secrets backed up from the Jenkins home directory. Once the pipelines match and the backup and restore procedure has been tested, retire the TeamCity projects in stages, keeping a read-only copy of the export for audit and history requirements.

Which TeamCity capabilities map to Jenkins, and which need rework

This table maps each TeamCity concept to its closest Jenkins equivalent and marks it as clean, needs rework or gap. Use it to scope the migration: clean rows can be translated mostly mechanically, rework rows need design decisions, and gap rows usually need a plugin or a process change that you should confirm before committing to a cutover date.

TeamCity capability	Jenkins equivalent	Status and notes
Build configurations	Jenkinsfile stages and steps, one per pipeline in source control	Needs rework. Each configuration becomes a stage or job, and parameters, triggers and steps must be rewritten by hand.
Build chains and snapshot dependencies	Parallel stages, triggered downstream jobs or a single pipeline with stage ordering	Needs rework. Snapshot dependencies pin exact upstream revisions, which Jenkins does not do natively, so confirm how each chain should pin inputs.
Templates	Shared libraries loaded with @Library and reusable pipeline functions	Needs rework. Template inheritance does not map one to one, so refactor common steps into versioned library functions.
Agent requirements	Agent labels and node selection in the pipeline, with agents provisioned as static nodes or Kubernetes pods	Clean for most cases. Requirements such as OS or installed tools become labels, but tool versions must be verified on each agent image.
Versioned settings (Kotlin DSL or XML)	Jenkinsfile and related configuration committed to Git, with Configuration as Code for controller settings	Needs rework. The exported .teamcity inventory is a reference, not an importable file, so rewrite it as code and review each change.
Bundled features (artifacts, test reporting, code coverage, notifications, Docker support)	Plugins from the Jenkins plugin catalog	Gap until confirmed. Several features are built in to TeamCity, so verify each one has a maintained plugin and check it against your Jenkins LTS baseline.
Secret parameters	Credentials stored in the Jenkins controller	Gap. Secret values cannot be exported from TeamCity, so each secret must be re-entered and rotated by its owner.

What data and integrations move, and what must be re-entered

A TeamCity move splits into three groups: what lives in versioned settings and can be read as code, what lives only in the TeamCity database and must be exported or archived, and what must be recreated by hand in Jenkins. The cards below cover each group, plus the Jenkins controller that will hold everything you rebuild.

Versioned settings as the inventory

Versioned settings in Kotlin DSL or XML give you a .teamcity directory that describes projects, build configurations, templates and build chains. Treat that directory as the migration inventory: every build configuration you map to a Jenkinsfile stage or shared library should trace back to a file in it. Check that the export is current and includes every project, because settings edited only in the web UI may not be versioned. Confirm which build configurations are not versioned before you begin.

Build history, artifacts and logs

Build history, published artifacts and logs are stored in the TeamCity server and are not converted into Jenkins records. Export the artifacts and logs you must keep for audit or release traceability before cutover, and record build numbers and commit hashes in a separate index. Confirm your retention requirement with your compliance owner, because the export and storage costs are yours to plan for.

Parameters and secure values

Plain parameters usually move with the settings files, but secure values (passwords and tokens stored as encrypted parameters) cannot be read back out of TeamCity in plain text. Plan to re-enter each one from a secrets source, such as a vault or Jenkins credentials store, and rotate it where the old value was shared widely. Do not copy secure values into a Jenkinsfile or the repository.

VCS roots and triggers

VCS roots define which repositories, branches and credentials a build reads, and triggers decide when a build starts. In Jenkins these become multibranch pipeline sources, webhooks or polling rules, and credentials you create again. Check each trigger against branch filters and schedules, and test that a commit to a protected branch starts the same build it did in TeamCity.

Notifications and issue tracker links

Build notifications and issue tracker integrations, such as links from commits to tickets, are configured per project in TeamCity and must be rebuilt in Jenkins through plugins or pipeline steps. List every recipient group, channel and tracker connection from the settings and confirm each one with its owner. Missing notifications are a common cause of silent failures after cutover.

Jenkins controller state

Jenkins keeps its configuration, installed plugins and stored secrets in $JENKINS_HOME on the controller, and the scaling guide recommends running builds on dedicated agents. Back up that directory on a schedule and test a restore before you rely on the new server. Decide early whether Configuration as Code YAML will hold non-secret settings, since that file can be versioned alongside the Jenkinsfiles.

Migration sequence from inventory to decommission

This sequence moves TeamCity projects to Jenkins in stages, so each build chain is proven on Jenkins before its repository leaves TeamCity. It ends with TeamCity agents and licenses retired only after every project has a verified cutover.

Export the .teamcity inventory
Enable versioned settings on the TeamCity project tree so the configuration is committed as a .teamcity directory, using Kotlin DSL or XML. The migration owner reads each build configuration, template, build chain, snapshot dependency, parameter and agent requirement from that directory and records them in one inventory. Separately, the team exports build history, logs and artifacts, since hosted or on-premises retention settings can remove them. Done when every project appears in the inventory and the history archive has been stored outside TeamCity.
Map configurations to Jenkins constructs
Build a mapping table that pairs each TeamCity object with its Jenkins equivalent: build configurations become Jenkinsfile stages, build chains and snapshot dependencies become sequenced or parallel stages and upstream triggers, templates become shared library code, and agent requirements become node labels. Mark every parameter and secure value as a secret to recreate in Jenkins credentials, because TeamCity secure values cannot be read back for export. Flag steps that depend on TeamCity-only features, such as specific build runners or IDE-linked reporting, so the team confirms their Jenkins plugin or script replacement. Done when the mapping table has an owner and no unmapped object remains.
Pilot one build chain on Jenkins
Choose one representative build chain, preferably one with a dependency and a deployment step, and write its Jenkinsfile in a branch of the repository. Set up a Jenkins controller and at least one dedicated agent with the labels the mapping table defines, and keep secrets and configuration backed up in the controller's home directory. Run the pipeline against real commits and compare artifacts, test counts and deployment results with the last TeamCity runs. Done when the pilot pipeline passes on Jenkins with output that matches TeamCity for the same commit.
Run both servers in parallel
Keep TeamCity building its existing projects while Jenkins runs the migrated pipelines on the same commits, so the team can compare results before anything is switched. Track differences in test results, timing, agent behavior and secret handling, and fix each one in the Jenkinsfile or the shared library. Confirm that only one server is allowed to publish artifacts or deploy to each environment at a time, to avoid duplicate releases. Done when the parallel results agree for an agreed set of projects over a set period that the team decides is sufficient.
Cut over project by project
Move one repository or project at a time: update the webhook or trigger so Jenkins builds it, disable the TeamCity build configurations, and confirm that the first production-path run succeeds. Use a cutover checklist per project covering triggers, credentials, branch rules, notifications, deployment targets and rollback steps. Record the owner who signed off each cutover. Done when every project has a signed checklist and TeamCity no longer triggers its builds.
Retire TeamCity agents and licenses
After all projects have cut over and the retention period for TeamCity history has been archived, stop the TeamCity build agents and release their licenses in line with the license terms in your agreement. Confirm with JetBrains which license records and Professional or Enterprise entitlements must be closed, and keep the final versioned settings export and history archive under your records policy. Shut down the TeamCity server only after the archive is verified and any audit or retention requirements are met. Done when TeamCity has no active projects, the archive is verified and the license closure is confirmed in writing.

How to run TeamCity and Jenkins in parallel and cut over

Run both servers side by side only for as long as you need to compare results, and decide up front which side owns each trigger. The main risk is duplicate work: a repository that still fires a TeamCity VCS trigger and a Jenkins webhook or SCM poll on the same commit will build twice, and if either pipeline contains a deploy stage, it can ship twice. Before the parallel period starts, list every VCS trigger, scheduled build, finish-build trigger and deployment step in the exported TeamCity settings, then disable the TeamCity side for each repository as it moves. Keep deployment credentials on one side only. Confirm with your Jenkins administrator that the Jenkinsfile deploy stages are gated (for example, to a branch or a manual input step) until cutover is signed off. Note that TeamCity secure parameters cannot be read back, so they must be re-entered in Jenkins credentials by the people who own them.

Agents can be shared or split, and the scaling guidance favors a split. The Jenkins scaling guide recommends dedicated build agents so the controller only handles HTTP requests and manages the build environment, and it keeps all configuration, plugins and secrets in $JENKINS_HOME on the controller, which is the directory you back up. Give each Jenkins agent a label that matches the TeamCity agent requirements you mapped, such as operating system or toolchain, and move TeamCity agents over in small groups so both servers do not compete for the same hardware. The scaling guide also describes adding controllers for new teams or projects, which suits organizations that want each team to own its own Jenkins. If uptime matters, place a primary and a backup controller behind a proxy such as HAProxy or F5, which routes traffic to the backup if the primary fails. Confirm with your platform team whether the backup holds a current copy of $JENKINS_HOME, because a standby without it cannot run your pipelines.

Rollback should happen at the repository level, not the server level. Keep the TeamCity configuration for each repository in version control and do not delete it until the Jenkins pipeline has passed on several real release cycles. If a Jenkins pipeline fails after cutover, re-enable the TeamCity trigger for that repository and disable the Jenkins trigger in the same change, then record the reason in the migration inventory. Agree in advance who may make that switch and how long a failure can run before rollback is triggered. Also confirm that Jenkins artifacts and any deployment targets are checked for the version that was actually released, so a rollback does not redeploy an older build over a newer one.

How the migration differs by size and starting point

A small team with a handful of build configurations, a few Linux agents and little cross-project coupling usually has the shortest migration. Each build configuration tends to map to one Jenkinsfile in the repository it builds, so the mapping is mostly a rewrite of steps that already exist as shell commands or Gradle, Maven or npm calls. The main decision is whether the team wants one Jenkins controller or a small set of pipelines that share a few steps.

Mapping effort: Few configurations means a manual translation is practical, and you can review each Jenkinsfile line by line against the original steps.
Agent work: Linux agents can usually run as Jenkins agents with labels such as linux and docker, with little extra setup.
Rework: Expect rework mainly around parameters, triggers and credentials, which were often set in the TeamCity UI and must be recreated.
Operating load: One controller with a backup plan is enough for most small estates, and the scaling guide's dedicated-agent advice still applies.
Secrets: TeamCity secure values cannot be exported, so each secret must be re-entered in Jenkins credentials.

Before you start, confirm with your team which configurations are still in use, since small estates often carry stale projects that do not need to move at all.

A team that already uses versioned settings in Kotlin DSL has a precise inventory. The .teamcity directory records build configurations, templates, parameters and dependencies as code, so the migration can start from files rather than screenshots. Review of those files shows what really exists, including configurations nobody remembers building.

Mapping effort: Build configurations, templates and dependencies can be read directly and turned into a migration spreadsheet.
Agent work: Agent requirements in the DSL can be translated into Jenkins labels, which makes the agent plan easier to review.
Rework: Parameters and steps still need rewriting in Jenkinsfile syntax, so the saving is in discovery rather than in code conversion.
Auditability: Git history gives a clear record of who changed each setting, which helps reviewers trace decisions.
Secrets: Parameter references in the DSL do not reveal values, so secret values still must be re-entered.

Check that the repository reflects what the server is actually running, since settings edited outside versioned mode may not match the committed files.

What usually goes wrong in a TeamCity to Jenkins move

Most failed CI migrations break on a small set of predictable issues: secrets that cannot be copied, builds that run twice, plugins that disappear, and dependencies or labels that were never written down. Each card below names one of these risks and the check to run before cutover, so the inventory from TeamCity's versioned settings becomes the control for the move.

Secrets that cannot be exported

TeamCity secure parameters are stored encrypted on the server, and their values are generally not readable back through the interface, so a move cannot copy them as plain text. Expect to re-enter every token, password and signing key into Jenkins credentials, and treat each one as a rotation event rather than a copy. Before cutover, list each secure value in the inventory, record which job uses it, and confirm with the owning team that a new value exists and has been tested in a non-production build.

Duplicate builds during the parallel run

Running TeamCity and Jenkins side by side is useful, but both servers can build the same commit, publish the same artifact or trigger the same deployment. Pipeline triggers, webhooks and polling schedules are easy to leave active on the old server. Before the parallel run starts, disable deployment steps and publishing on one side, assign each repository to a single active trigger owner, and keep a written list of which system owns each project.

Plugins missing after a LTS upgrade

Jenkins LTS 2.580.1 stopped bundling several plugins, including the bouncycastle API, SSH server and JUnit plugins, so a server that relied on them after an upgrade can fail builds or lose SSH and test reporting. Build a list of every plugin your pipelines call, pin versions in code, and install the bundled-to-optional plugins explicitly before upgrading. Test a controller upgrade in a staging instance that mirrors the production plugin set.

Snapshot dependencies mapped in the wrong order

TeamCity snapshot dependencies and build chains decide which configuration runs first and whether artifacts from upstream builds are reused. When these are rewritten as Jenkinsfile stages, a parallel stage or a missing copy-artifact step can let a downstream job test a stale or absent build. For each chain in the versioned settings, draw the dependency graph, write the matching stage order, and confirm that every consumed artifact is fetched from the exact upstream build number.

Build history and artifacts lost at cutover

TeamCity keeps build history, artifacts and logs according to its own cleanup rules, and decommissioning the server ends access to them. Auditors and incident responders often need the history for past releases. Before retiring TeamCity, export the artifacts needed for supported releases, archive build logs and test reports to storage you control, and record the retention period you need in writing so the export scope is agreed in advance.

Agent labels drifting from the original

TeamCity agent requirements, such as installed SDKs, operating system or Docker availability, often exist only as agent pool settings and agent properties. When Jenkins agents are built with different tool versions or labels, the same Jenkinsfile can pick a different machine and produce different results. Map each TeamCity requirement to a named Jenkins label, document the tool versions on each agent image, and check periodically that agents still match the labels used in the pipelines.

What drives cost and duration, and how to keep each down

This table lists the factors that most change the effort of moving TeamCity projects to Jenkins, why each one adds work, and how to reduce it. Use it to shape a written scope before asking for a quote, since the largest effort usually comes from undocumented configuration and secrets rather than from the number of projects.

Driver	Why it adds work	How to keep it down
Build configurations and build chains	Each configuration becomes a stage or job, and each snapshot dependency or chain becomes an ordering rule that must be reproduced and tested.	Export the versioned settings, group configurations by chain, and retire unused configurations before converting.
Template reuse	Templates that many configurations inherit must become shared library functions, and each override must be found and preserved.	Count template inheritance in the export first, then convert the most-used templates once and reuse them.
Parameters and secure values	Secure values cannot be read back from TeamCity, so each one must be re-entered in Jenkins credentials and its owner confirmed.	Ask the team to list secret owners and rotate values during cutover rather than copying them.
Agent platforms and requirements	Each agent requirement (OS, tools, Docker, Windows or macOS) must map to a Jenkins agent label and a provisioned node.	Group agents by platform, reduce the number of distinct requirement sets, and standardize tool versions.
Plugin dependencies	TeamCity features such as build features and reports map to Jenkins plugins that must be selected, pinned, tested and maintained after cutover.	List every build feature in use, prefer plugins already in use at your organization, and remove unused ones.
Test and deployment integrations	Test reporting, issue trackers, artifact repositories and deployment targets each need a configured connection and an authentication path.	Confirm each integration endpoint and credential early, and migrate the deployment steps with their approvals.
Build history and artifacts	History and artifacts do not transfer as live builds, so retention decisions and export or archive work must be scoped.	Decide which history and artifacts must be kept, export only those, and agree on a retention period in writing.
Number of teams and controllers	Each team with its own folders, permissions and controller adds setup, access design and operating work.	Consolidate teams onto shared controllers where possible, and ask for the controller design as a scope deliverable.

Cost components: what is one-time and what recurs

The main thing to understand about a TeamCity to Jenkins move is that the software license is not where the cost sits. Jenkins is distributed under the MIT License, so there is no per-agent license to buy and no build configuration cap to hit. What you pay for is people and infrastructure: the migration design and mapping work, the rewrite of build configurations and build chains into Jenkinsfiles, the controller and agent machines (or Kubernetes capacity) that run them, and the staff time to keep the server healthy. Ask any vendor or partner to split their quote into these components so you can see who is paid for what and which items are one-time.

Most of the one-time cost falls in the first project phase. It covers building the inventory from your versioned settings export, deciding which TeamCity templates become shared libraries, rewriting pipelines, recreating credentials in Jenkins, and running old and new pipelines side by side until results match. Costs rise with the number of build configurations, the number of snapshot dependencies that need to be expressed as stages, and how many Windows or specialized agents you need. Ask for the rewrite effort to be stated per pipeline group, so the quote shows what happens if the inventory turns out larger than expected.

The recurring cost is operating the server. Jenkins publishes LTS releases on a regular cycle, and plugin updates arrive separately, so someone must schedule controller upgrades, check plugin compatibility, and confirm that Java support still matches the release you run. Note that LTS 2.580.1 stopped bundling several plugins, so upgrade work includes installing those plugins explicitly. Backup of $JENKINS_HOME and periodic restore tests, agent image maintenance and 24-hour or business-hours support are also ongoing. Ask partners whether these are priced as a retainer, what response commitments are included, and what the written scope excludes.

Questions buyers ask before moving from TeamCity to Jenkins

How much effort does a TeamCity to Jenkins migration take?

Effort depends mostly on how many build configurations, build chains, templates and agent types you run, and on how much of the logic lives in custom plugins or scripts. Start by exporting your settings with versioned settings enabled so you have a complete inventory, then count the items that need a rewrite: each build configuration becomes a pipeline stage or Jenkinsfile, each template becomes a shared library, and each agent requirement becomes a label. Ask any provider to scope the work from that inventory in writing, and ask them to state which items they treat as straightforward and which as rewrites.

What sets the timeline for moving CI from TeamCity to Jenkins?

The timeline is set by the size of the inventory, the number of teams that must test pipelines before cutover, and how many systems the builds deploy to. Parallel running is usually the longest phase, because both servers must build the same repositories until results match. No duration is supplied for this migration, so ask for a timeline tied to phases in the written scope and confirm which of your release freezes, change windows and audit dates it has to fit around.

What does the migration need from our engineering team?

Your team needs to supply access, decisions and domain knowledge. Engineers who own each project must confirm which builds are still in use, which parameters and dependencies matter, and what each deployment step is supposed to do. Platform engineers need to decide how Jenkins controllers, agents and backups will be run, and security staff need to approve how credentials will be stored. Plan for reviewers to check each converted pipeline against the original build output before it replaces the TeamCity run.

Can our own team migrate from TeamCity to Jenkins without outside help?

Yes, a capable internal team can do it, provided it has people who know both Jenkins pipelines and your TeamCity setup. The work is mostly conversion and testing, and it is easier when one group owns the mapping of build chains to stages. The main risks are missed implicit dependencies, forgotten agent requirements and secrets re-entered incorrectly. If internal capacity is limited, ask a provider to take on the inventory and conversion under a fixed scope, and keep ownership of the final pipelines in your team.

How are TeamCity secrets handled when we move to Jenkins?

TeamCity secure values cannot usually be exported in readable form, so plan to re-enter them in Jenkins credentials. Other CI platforms follow the same pattern: GitHub's REST API returns Actions secret names without values, and Bitbucket secured variables can only be replaced or deleted. Create the new credentials in Jenkins, restrict them to the folders or pipelines that need them, and rotate any value that has been widely shared. Hosted CI services hold secrets for every connected project, which is one reason many teams prefer keeping credentials on infrastructure they control. Confirm with your provider how secrets will be recorded and reviewed during cutover.

What happens to TeamCity build history and artifacts during the move?

Build history, artifacts and logs do not transfer into Jenkins automatically, so export what you need before TeamCity is shut down or its retention changes. Decide which records must be kept for audit or incident review, such as release artifacts, test reports and deployment logs, and store them in an archive your organization controls. Jenkins keeps its own build history on the controller, so set retention rules for it deliberately. Confirm the retention periods your compliance and release processes require before cutover.

Does Jenkins require a license fee that TeamCity agents do not?

Jenkins is distributed under the MIT License, so there is no license fee to run the open-source server or its agents. Costs shift to infrastructure, the people who operate Jenkins, plugin maintenance, upgrades and any support contract you choose to buy. TeamCity Enterprise licenses agents, while Jenkins agents are limited only by your hardware. Ask for a cost breakdown that separates one-time migration work from recurring operations, and confirm who pays for each item.

How DeployOpen scopes and runs a TeamCity to Jenkins migration

DeployOpen is a Chainscore Labs company that plans, implements, customizes, integrates, hardens, backs up and documents self-hosted open-source platforms inside the client's own cloud accounts, data centers or air-gapped networks. For a TeamCity to Jenkins move, we start from the written inventory of your TeamCity projects and agree the scope, deliverables and timeline in writing before any work begins.

How we scope

Inventory every TeamCity project from its versioned settings, Kotlin DSL or XML, and map build configurations, chains and dependencies.
Agree in writing which pipelines, agents, secrets handling and history exports are in scope and which stay on TeamCity.
Confirm with you which secure values can be re-entered by owners and which must be recreated in a credentials store.

How we build

Convert build chains and snapshot dependencies into Jenkinsfile stages, then review each pipeline with the owning team.
Replace TeamCity templates with shared libraries and set up agents with labels that match the original build requirements.
Test pipelines against sample commits and compare build outputs, test results and artifacts with the TeamCity baseline.

How we hand over

Document controller and agent setup, the Jenkinsfile conventions, shared library usage and the backup scope under $JENKINS_HOME.
Deliver a migration log that lists each TeamCity configuration, its Jenkins equivalent and any items left for manual follow-up.
Walk your platform, security and development leads through runbooks and a cutover checklist before TeamCity is retired.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover.
Ask any quote to separate one-time migration work from recurring support, upgrades and plugin maintenance.
Confirm with your security and compliance teams which evidence they need, since DeployOpen prepares evidence but does not issue audit reports.

Migrate from TeamCity to Jenkins