Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Migrate from TeamCity

yesterday4 min read
Cloud
Server 3.x
On This Page

This document provides an overview of how to migrate from TeamCity to CircleCI.

Quick start

CircleCI has various differences in setup and configuration from TeamCity. For the best experience of trying CircleCI, we recommend getting started with the following:

  1. Read (or at least browse) this document to solidify conceptual differences.

  2. Quickly build and run a simple Hello World job in any repository. This configuration demonstrates the simplicity of our YAML setup, and it showcases how to define both an execution environment and the steps to run within it. All jobs on CircleCI share this format.

  3. Once you understand the config, modify the executor and the individual steps to meet your needs. For example, a Rails project may use a Ruby container image and run bundler commands. Consult our Examples and Guides Overview for various examples in different languages and frameworks.

  4. After finishing one job, setup your other jobs on CircleCI and then configure a workflow. This would essentially migrate your Build Chain.

  5. Next, optimize your jobs with advanced features to see how much faster your builds could run on the CircleCI platform.

  6. Throughout this process, consult the Configuration Reference for a list of all available configuration on the CircleCI platform.

Why migrate to CircleCI?

CircleCI is a modern CI/CD tool aimed at performance and developer productivity. With a flexible system for configuration, you can define complex workflows and jobs for your application’s specific needs.

Configuration As Code

The majority of CircleCI’s configuration is done via YAML. It is easy to maintain and trivial to learn, and your CI/CD pipeline can be tracked and versioned like the rest of your source code.

Auto-Scaling Architecture

All execution environments are dynamically created according to your config and terminated on completion of tasks. You can run one - or hundreds - of jobs concurrently without any hassle or overhead.

Flexibility

CircleCI is vendor and tool-agnostic. Our config allows integration with any platform or cloud provider that has an API. See our integrations page for existing partnerships. Dependencies and libraries can be installed ad-hoc in your job, and we offer dependency caching to speed up subsequent builds.

Shareable, Reusable Configuration

Steps, execution environments, and jobs can be templated, parameterized, shared, and reused across different projects and teams using CircleCI orbs. Take advantage of the numerous integrations and orbs already written for you.

We have various other features that set our solution apart. Sign up for a free account today and try us out.

Concepts

High-level differences

  • CircleCI and TeamCity share the concept of projects.

  • TeamCity’s Build Configurations are equivalent to CircleCI’s jobs, which are atomic elements of work consisting of many steps or commands to achieve a goal (for example, run unit tests).

  • TeamCity has traditionally used the UI to configure most builds, with Kotlin Script configuration being a newer, recent feature. CircleCI uses YAML to configure the majority of pipeline functionality.

TeamCity settings.ktsEquivalent CircleCI config.yml
import jetbrains.buildServer.configs.kotlin.v2019_2.*
import jetbrains.buildServer.configs.kotlin.v2019_2.buildSteps.script

version: "2019.2"

project {
  buildType(HelloWorld)
}

object HelloWorld: BuildType({
  name = "Hello World"
  steps {
    script {
      scriptContent = "echo 'Hello World!'"
    }
  }
})
version: 2.1
workflows:
  hello-workflow:
    jobs:
      - hello-job

jobs:
  # Define job
  hello-job:
    # Define environment
    docker:
      - image: cimg/base:stable

    # Define steps for job
    steps:
      - checkout
      - run: echo "Hello World!"
TeamCity settings.kts
import jetbrains.buildServer.configs.kotlin.v2019_2.*
import jetbrains.buildServer.configs.kotlin.v2019_2.buildSteps.script

version: "2019.2"

project {
  buildType(HelloWorld)
}

object HelloWorld: BuildType({
  name = "Hello World"
  steps {
    script {
      scriptContent = "echo 'Hello World!'"
    }
  }
})
Equivalent CircleCI config.yml
version: 2.1
workflows:
  hello-workflow:
    jobs:
      - hello-job

jobs:
  # Define job
  hello-job:
    # Define environment
    docker:
      - image: cimg/base:stable

    # Define steps for job
    steps:
      - checkout
      - run: echo "Hello World!"
  • Instead of Build Chains, CircleCI has Workflows, which define dependencies and flow between jobs.

  • A Pipeline refers to all configuration, workflows, and jobs for a project. This multi-layer structure allows for strong flexibility and separation of concerns for different workloads.

TeamCity Build ChainEquivalent CircleCI Workflow
project {
  sequence {
    build(Compile)
    parallel {
        build(Test1)
        build(Test2)
    }
    build(Package)
    build(Publish)
  }
}

/* BuildType definitions assumed
version: 2.1
workflows:
  build-deploy:
    jobs:
      - Compile
      - Test1:
          requires:
            - Compile
      - Test2:
          requires:
            - Compile
      - Package:
          requires:
            - Test1
            - Test2
      - Publish:
          requires:
            - Package

# Job definitions assumed
TeamCity Build Chain
project {
  sequence {
    build(Compile)
    parallel {
        build(Test1)
        build(Test2)
    }
    build(Package)
    build(Publish)
  }
}

/* BuildType definitions assumed
Equivalent CircleCI Workflow
version: 2.1
workflows:
  build-deploy:
    jobs:
      - Compile
      - Test1:
          requires:
            - Compile
      - Test2:
          requires:
            - Compile
      - Package:
          requires:
            - Test1
            - Test2
      - Publish:
          requires:
            - Package

# Job definitions assumed

For more information on CircleCI Concepts, visit our Concepts and Pipelines documentation pages.

Configuration

Environment

TeamCity requires setting up a build agent with the required OS and tools installed and a corresponding Build Configuration. In CircleCI, all job configurations have an Executor definition, and CircleCI handles spinning up said agents for you. See our list of available executors.

version: 2.1
jobs:
  my-mac-job:
    # Executor definition
    macos:
      xcode: "12.5.1"

    # Steps definition
    steps:
      - checkout
      # ...etc.

Steps

In TeamCity, build steps are chosen from a list of defined Runner Types (for example, Visual Studio, Maven, Gradle, etc.). On CircleCI, step definition can flexibly take any commands you would run in a Terminal or Command Prompt.

Subsequently, this flexibility allows steps to be adapted to any language, framework, and tool. For example, a Rails project may use a Ruby container and run bundler commands. A Node.js project may use a Node container and npm commands. Visit our Examples and Guides Overview for various language and framework examples.

TeamCity StepsEquivalent CircleCI Steps
project {
  parallel {
    build(Gradle) # Assume agent configured
    build(Maven)  # Assume agent configured
  }
}

object Gradle: BuildType({
  name = "Gradle"

  steps {
    gradle {
      tasks = "clean build"
    }
  }
})

object Maven: BuildType({
  name = "Maven"

  steps {
    maven {
      goals = "clean package"
    }
  }
})
version: 2.1
workflows:
  parallel-workflow:
    jobs:
      - Gradle
      - Maven

jobs:
  Gradle:
    docker:
      - image: cimg/openjdk:17.0.1
    steps:
      - checkout # Checks out source code
      - run:
          name: Clean and Build
          command: ./gradlew clean build

  Maven:
    docker:
      - image: cimg/openjdk:17.0.1
    steps:
      - checkout # Checks out source code
      - run:
          name: Clean and Package
          command: mvn clean package
TeamCity Steps
project {
  parallel {
    build(Gradle) # Assume agent configured
    build(Maven)  # Assume agent configured
  }
}

object Gradle: BuildType({
  name = "Gradle"

  steps {
    gradle {
      tasks = "clean build"
    }
  }
})

object Maven: BuildType({
  name = "Maven"

  steps {
    maven {
      goals = "clean package"
    }
  }
})
Equivalent CircleCI Steps
version: 2.1
workflows:
  parallel-workflow:
    jobs:
      - Gradle
      - Maven

jobs:
  Gradle:
    docker:
      - image: cimg/openjdk:17.0.1
    steps:
      - checkout # Checks out source code
      - run:
          name: Clean and Build
          command: ./gradlew clean build

  Maven:
    docker:
      - image: cimg/openjdk:17.0.1
    steps:
      - checkout # Checks out source code
      - run:
          name: Clean and Package
          command: mvn clean package

Build templates/meta-runners

CircleCI’s equivalent of Meta-Runners and Build Templates is orbs, which are templatizable, shareable configuration. Read more about them in our orbs documentation.

Complex builds

For larger and more complex builds, we recommend moving over in phases until you get comfortable with the CircleCI platform. We recommend this order:

  1. Execution of shell scripts and Docker compose files

  2. Workflows

  3. Artifacts

  4. Caching

  5. Triggers

  6. Performance options

Resources


Suggest an edit to this page

Make a contribution
Learn how to contribute