How to export your data from TeamCity before you leave
A renewal, a licensing change or a data residency requirement is usually what forces a TeamCity move, so the export has to start with the configuration you already have. Project configuration can be exported as versioned settings, which commit a .teamcity directory to the repository in either Kotlin DSL or XML. Secure values, most agent-side state and build history need separate handling, because TeamCity's versioned settings do not carry them and the export will not give you usable copies of them. Plan for those items as their own work stream from the start.
Treat the versioned settings export as your migration inventory. Review each build configuration, template, build chain, parameter, VCS root and agent requirement in the committed files, and record where each one will land in the target system, whether that is a Jenkinsfile stage, a Woodpecker workflow or a GitLab CI/CD job. Parameters marked as secure values must be recreated by an authorized person in the new platform, since the stored values cannot be read back out. Confirm this with your TeamCity administrator and your secrets owners before you sign off the inventory, and record which secrets must be rotated rather than copied.
Build history, artifacts and logs are the items most likely to be lost. Export or archive what your retention or audit obligations require, and confirm with your compliance lead which records must be kept and for how long, because TeamCity's own retention settings govern what still exists on the server. Check your TeamCity version's documentation for the exact export and archive options, and test a restore of a sample project in a non-production environment before you retire the server.
What you can export from TeamCity and how
This table lists each TeamCity data type you need for a migration, the export method and format it uses, and the limits you must confirm. Read it as an inventory checklist: versioned settings cover configuration as code, while secrets, build history, artifacts and logs need separate handling. The main takeaway is that only the configuration layer lands in Git automatically, so plan a separate export for everything else.
| Data type | Export method and format | Limits and what to confirm |
|---|---|---|
| Build configurations and projects | Committed to the .teamcity directory when versioned settings are enabled, in Kotlin DSL or XML | Confirm the default format for your version and whether projects outside versioned settings are covered |
| Templates | Exported with project settings in the same .teamcity directory | Confirm that template inheritance is preserved in the format you choose |
| Parameters | Written as configuration parameters within versioned settings | Confirm how parameters that reference other parameters appear in the exported files |
| Secure values | Stored encrypted, so values are not readable in plain text after they are set | Plan to re-enter secrets in the target platform and confirm current behavior in TeamCity's documentation |
| Agent requirements | Written as build configuration requirements within versioned settings | Agent pools and agent-side settings sit outside the repository, so inventory them separately |
| VCS roots | Included with project settings when versioned settings cover them | Confirm whether VCS root credentials are exported, since they behave like secure values |
| Build history | Not part of versioned settings, so use the TeamCity REST API or your own reporting | Confirm retention settings and which history fields the API returns for your version |
| Build artifacts | Stored on the TeamCity server or agents and copied out with your own tooling | Confirm artifact retention and storage paths before cleanup rules remove older builds |
| Build logs | Viewed in the web interface, with export options that depend on your version | Export logs only where audit needs them, and confirm log retention in your installation |
What does not export and the workaround for each
Versioned settings give you the project structure, but not everything TeamCity knows about your builds. The cards below cover the items that stay behind, from secure values to agent state and server access, and the workaround for each. Treat this list as the second half of your migration inventory.
Secure parameters and password fields
Secure parameter values and password-type fields are write-only in TeamCity. The versioned settings reference them by name, but the values themselves are not written to the exported files, and the UI will not reveal them again. Before you migrate, list every secure parameter a build uses, then re-enter each value in your own secrets store, such as a managed vault or your CI platform's secret mechanism. Confirm with the owners of each credential that it can be rotated, since the old value may have been shared across projects.
Agent-side state and local files
Anything stored on a build agent sits outside the server and never reaches the versioned settings. This includes installed tools, SDKs and licenses, Docker image caches, custom scripts in agent home directories, certificates, and SSH keys used for deployments. Inventory each agent pool by hand, noting OS, installed software and any file paths your build steps assume. Then define the same toolchain in container images or agent provisioning code, so the new runners can be rebuilt from source instead of copied.
Users, groups and permission roles
TeamCity users, groups, role assignments and project-level permissions are server data, not project code, so they are not part of the exported configuration. Export the list of users and groups from the administration pages, along with the role each one holds on each project. Map these to the access model of the target platform and to its identity provider, and confirm that every service account used by a trigger or deployment still has an owner. Expect some permissions to need redesign rather than a one-to-one copy.
Build history, logs and artifacts
Build history, logs and artifacts live in the TeamCity data directory and are not written to the versioned settings. They are also the data most likely to be lost, because retention rules remove old builds on a schedule. Check the retention settings for each project, then decide which builds, test reports and artifacts must be archived before cutover. Store the archive in storage you control and record which build numbers it covers, so auditors can trace a release to its evidence.
Server integrations, notifications and plugins
Connections to issue trackers, VCS roots with stored credentials, notification rules, cloud profiles, and third-party plugins are configured in the server rather than in project files. Some appear in the versioned settings, but credentials and plugin-specific settings often do not. List every connection and notification rule from the administration pages, and record who receives each alert. Then rebuild each one on the target platform and test it with a non-production trigger before cutting over.
Build trigger history and pending queue
Build queue contents, trigger state, and the record of which commits have already been built are runtime data, so they do not move with the configuration. Without that record, the new platform may rebuild commits that were already tested or skip ones that were never built. Before cutover, note the last successful build for each branch that feeds a release, freeze new merges during the switch if your process allows, and confirm that the first builds on the new platform match what TeamCity produced for the same commit.
The sequence for a complete TeamCity export
The sequence turns a TeamCity server into a versioned, reviewable inventory of projects, build history, artifacts, logs and parameters that a migration team can work from. Each step ends with a check so gaps show up before the old server is retired.
Enable versioned settings on every project
A TeamCity administrator turns on versioned settings for each project that holds build configurations, so the server writes its configuration out as files. Start with the root project and confirm each sub-project shows the same synchronization status in the administration area. Done means every project in scope reports that its settings are stored in version control, with no pending changes waiting to be committed. Projects that were never synchronized are the most common source of missing configuration later, so check the full project tree, not only the projects people use daily.
Commit the .teamcity directory to Git
Once versioned settings are on, TeamCity writes a .teamcity directory into the repository it is linked to. The administrator or platform engineer reviews that directory and commits it to a dedicated export branch, keeping it separate from the working branch so the export is easy to find later. Done means the repository holds a complete .teamcity tree, and a fresh clone of that branch contains the build configurations, templates and project settings the team expects. Keep a copy of the repository itself, because the directory alone does not hold build history or logs.
Choose Kotlin DSL or XML as the inventory format
The team decides which format becomes the authoritative inventory: the Kotlin DSL files that TeamCity generates for projects, or the XML settings that the server stores. Kotlin DSL is easier to read and review for most teams, while XML is the more literal copy of server state. Whichever format is chosen, record it in the migration plan and do not mix the two in the inventory. Done means the chosen format is committed, and a reader can open a build configuration file and identify its steps, triggers, agent requirements and parameters without running TeamCity.
Export build history and artifacts before retention runs
Build history, artifacts and logs are held by the TeamCity server under its own retention settings, and they are not part of versioned settings. The administrator should review the retention rules for each project and export the builds that the organization must keep, using the TeamCity REST API or the server's data directory under the supervision of the server owner. Artifacts that are needed for audit or rollback should be copied to storage the organization controls. Done means each exported build has an identifier, a status, a timestamp and a checksum of its artifacts, and the list of exported builds is saved next to the settings. Confirm the exact retention settings and export options in the documentation for the TeamCity version in use, because they vary between releases.
Collect parameters and secure value references
Parameters and their values are the step that teams most often skip. Build configuration parameters are visible in the versioned files, but values stored as secure tokens are not written out in readable form, so the export records which secrets exist, which configurations use them and who owns each one. The platform owner should produce a parameter list per project and mark each secure value as needing re-entry in the target system. Done means every secure parameter has a row in the inventory with its owner and the build configurations that depend on it, and no secret value appears in the export or in any ticket.
Collect logs and agent inventory
Build logs and the list of agents show how the build environment actually ran. The team should export logs for the builds retained in the previous step, and record each agent's name, operating system, installed tools, pool membership and any agent requirements that builds depend on. This is the information needed to map agents to Jenkins labels or Woodpecker runners later. Done means every active agent appears in the inventory with its requirements, and every build configuration that relies on a specific agent or tool points to an entry in that list.
Verify object counts and sample builds
The team compares the number of projects, build configurations, templates, parameters, agents and exported builds in TeamCity against the same counts in the inventory. Differences need a written explanation, such as a deliberately archived project. Then the team picks a sample of builds from different projects and checks that the exported status, timestamp, log and artifact checksum match the source. Done means the counts reconcile, the sample builds match, and a named owner signs off the inventory before any project is cut over. The sign-off record becomes the baseline for the migration.
Turning the export into a migration inventory
The committed .teamcity directory is only useful if it becomes a working inventory. Treat each file as a source record and list every build configuration, build chain (snapshot dependency), template, agent requirement and VCS root as its own row. Each row should name its target element on the destination platform: a Jenkinsfile stage or shared library call in Jenkins, a workflow file in Woodpecker CI, or a job in a .gitlab-ci.yml file in GitLab CI/CD. The column-by-column mapping rules belong to the migration pages, so use this inventory to decide scope and ownership, then follow those pages for the translation itself. Add a column for the project owner and a column for the status of each row so that the inventory also serves as a cutover checklist.
Add a separate register for secrets. The .teamcity files show where parameters and secure values are referenced, but the secret values themselves are not part of the export, and TeamCity does not reveal them in a form you can copy. For each secure value, record the name, the build configurations that use it, the target system that will hold it, and the person who will recreate and rotate it. Confirm with your security team which of these values are deployment credentials, signing keys or cloud access tokens, since those usually need new issuance rather than a copy. Also check whether any parameter that looks like a plain value is actually a password or token. Plain parameters that carry sensitive data will otherwise slip into a new pipeline file under version control.
Finally, record what the export does not cover. Build history, artifacts and logs are not in the versioned settings, so the inventory should list which projects need those retained, where they will be archived, and for how long your policy requires. Confirm the retention period with your compliance owner before you delete anything from TeamCity. Once every row has a target, every secret has an owner and every retained artifact has an archive location, the inventory is complete enough to start the first pilot pipeline.
What to plan before the TeamCity contract ends
The export itself is the last step of a longer exit. The decisions below set the freeze window, the history cutoff, the license footprint and the overlap period, and each one should be settled with JetBrains or the reseller in writing before the renewal date is fixed.
Freeze window for configuration changes
Every change made in the TeamCity UI after the export snapshot is lost to the new platform unless it is captured again. Decide whether teams can keep editing build configurations during the migration, and if so, how those edits will be re-exported. Ask whether versioned settings can be committed on a branch so the snapshot is reproducible. Agree a single cutoff commit that becomes the migration inventory.
Starting the history export early
Build history and artifacts should be exported before the contract ends, because hosted CI retention is short and self-managed servers may purge data on their own schedule. Confirm with JetBrains or the reseller how long build history, artifacts and logs are kept on your server, whether purge rules can be changed, and which export formats are offered. Estimate the storage needed for artifacts so the archive target is sized before the work starts.
Agent and license counts in use
Count the build agents that ran jobs in the last few months, including Windows agents, cloud agents and any agents held in reserve. Compare that number with the licensed agent count and the build configuration count in the current contract. Ask JetBrains or the reseller in writing how a true-up is calculated if the count changes before the end date, and whether unused licenses can be released at renewal.
Secrets that cannot be exported
Secure parameter values are normally write-only, so the export will carry their names and references but not their values. Build an inventory of every credential, signing key and token used by a build, then plan to re-enter those values into the new platform's secret store. Ask the vendor in writing whether secure values can be decrypted for migration purposes, and document the answer, since most platforms will refuse.
Parallel running and cutover window
Plan a period in which TeamCity and the replacement run the same pipelines, so builds can be compared before the old server is switched off. Decide which branches and projects move first and which stay on TeamCity until the last day. Confirm with JetBrains or the reseller the exact date on which the license term, support and access end, and whether read-only access to the server remains after that date for audits.
Retained evidence and access after termination
Regulated teams often need build logs, approvals and deployment records for audits after the server is gone. Decide which records must be kept, where they will be stored and who can read them. Ask the vendor in writing what happens to server data at termination, how long it remains available and in what format it can be downloaded, so the evidence plan is not built on assumptions.
Questions buyers ask before they export TeamCity data
How much effort does a full TeamCity export take?
The effort depends mostly on how many projects and build configurations the server holds, how much build history you need to keep, and how large the stored artifacts are. Start by counting projects, build configurations, templates, agents and the number of days of history your auditors or release managers want. A small server with a few projects and recent history is a short inventory exercise. A server with hundreds of configurations, years of logs and large artifacts needs a sorting pass to decide what moves, what is archived and what is dropped. Ask for the export scope in writing before work starts, including which artifact and log retention periods are in scope.
Can our team export TeamCity data without outside help?
Often yes for the configuration, and the harder parts usually need engineers who know both TeamCity and the target platform. Turning on versioned settings lets your own team commit a .teamcity directory in Kotlin DSL or XML, which gives you a readable inventory of projects, build configurations and parameters. Build history, artifacts and logs need a deliberate export plan because TeamCity's retention settings decide what still exists. Secrets need a separate plan because they cannot be read back from most CI systems. Confirm your team's TeamCity administration experience, and ask a partner to scope any part your engineers have not handled before.
What work do our engineers and security staff need to contribute?
Engineers own the mapping of build configurations, build chains, templates and agent requirements to the new platform, and they verify that each migrated pipeline produces the same artifacts. Security staff own the decisions about secret handling, access to exported logs and artifacts, and where the export files are stored while they are in transit. Plan time for a reviewer who can confirm which parameters are plain text and which are secure values, because those need different treatment. Also name an owner for signing off the final inventory. Ask any implementation partner to list these roles and the review points in the written scope.
How long does an export take, and what sets that duration?
Duration is set by the size of the inventory, the amount of history and artifacts to move, the number of people reviewing the output, and how many build configurations must be recreated by hand. The supplied research does not give a general duration for TeamCity exports, so treat any figure you hear as a quote to verify against your own server. The fastest part is usually committing versioned settings. Slower steps include reviewing secure values, reconciling agent pools and confirming that migrated builds pass in a test environment. Ask for a timeline that separates inventory, history export, secret handling and build validation.
What happens to our secrets during a TeamCity export?
Secure values in TeamCity should be treated as non-exportable and must be re-entered in the new platform by an authorized person. Most hosted and self-managed CI systems return secret names without values or let you replace them only, so the plain text cannot be pulled out in a clean migration. The supplied research shows the same pattern across other CI vendors, and it also shows why hosted CI secrets deserve caution: CircleCI's January 4, 2023 incident report told customers to rotate secrets after an attacker exfiltrated environment variables and keys. Plan to rotate credentials you migrate, record who re-enters each secret, and confirm the exact behavior of your TeamCity version with JetBrains documentation before you start.
Will build artifacts and logs survive the export?
They survive only if someone exports them before retention deletes them, so check your current retention settings first. TeamCity keeps build history and artifacts for the periods your administrators configured, and older items may already be gone. Hosted CI services generally keep artifacts for shorter windows than many organizations expect, which is why the export should start with a retention audit. Decide which artifacts must be preserved for audit or rollback, which logs are needed for incident history, and which can be dropped. Ask your storage team to confirm capacity in the destination before copying large artifact sets.
Does the export affect our existing TeamCity licenses or agents?
Exporting configuration does not change your licensing by itself, but running both systems in parallel may. Check your current edition, build configuration count and agent count before you start, since TeamCity Professional has limits and blocks new builds when agents exceed the license. Keep the source server available in read-only form until the migrated pipelines are verified. Confirm the licensing terms with JetBrains for any period where both servers run, because the export plan should not assume that overlap is free.
How to verify the export is complete
The most useful verification is a diff. Once versioned settings are enabled and the .teamcity directory is committed, export the configuration a second time from the running server and compare the two trees in your Git client. Any project, build configuration, template, parameter or agent requirement that differs, or that exists only on the server, means the committed copy is not yet a complete inventory. Confirm that the settings were committed on the branch you intend to migrate from, because a fresh export from a different branch will hide gaps. Keep the diff output with the migration record so the reviewer can see what was checked and when.
Next, reconcile the inventory against the server itself. Walk the project tree in the TeamCity administration interface and confirm that every project, build configuration and build chain (snapshot dependency) appears in your list with a target equivalent, such as a Jenkinsfile stage, a Woodpecker workflow or a GitLab CI job. Check the agent pools and the requirements attached to each configuration, since these are often the easiest items to lose. Ask the engineering owner of each project to sign off on their list. Items that nobody claims are usually abandoned pipelines, and those are a decision for the business, not something to migrate by default. Finally, test-run a sample of builds on the target platform and record the results. Pick builds that cover the risky cases: a multi-step chain, a build that publishes artifacts, a deployment with secure parameters, and a build on a Windows agent if you run one. Compare outputs, test counts and artifact checksums against the last successful TeamCity build. Also keep a secrets register that lists each secured value, the system that holds it now, the person who re-entered it and the date. Because secret values cannot be read back from TeamCity, this register is the only evidence that the replacement is correct and that nothing was left behind.
How DeployOpen scopes and delivers a TeamCity exit
DeployOpen plans and delivers TeamCity exports as fixed-scope engagements inside your own infrastructure. We agree the scope, deliverables and timeline in writing before work starts, then build the migration inventory, extract what can be extracted and document what cannot.
How we scope
- Inventory every project, build configuration, template and agent pool in the TeamCity instance before quoting
- Confirm whether versioned settings are enabled and which DSL or XML format the repositories use
- Agree in writing which secrets, artifacts and build history are in scope, and which are retained by the owner
How we build
- Enable versioned settings where needed and commit the .teamcity directory to a controlled repository
- Script the extraction of build history, logs and artifacts into storage you own, within the retention you require
- Map parameters and secure values into a secrets inventory, recording which values must be re-entered by hand
How we hand over
- Deliver a migration inventory listing each build configuration, dependency and agent requirement with its target equivalent
- Document every gap, such as secure values that cannot be read back, so your team knows what to re-create
- Provide the export scripts, runbooks and evidence of what was exported, written so your own engineers can repeat it
How we support
- Support the cutover and validation of exported projects against the agreed scope in your environment
- Offer ongoing support, upgrades and continuous testing as a retainer after the engagement closes
- Confirm with your team and vendor any TeamCity export feature or version detail that your instance depends on
