Migrate from TeamCity

Cloud

Server 3.x

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:

Read (or at least browse) this document to solidify conceptual differences.
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.
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.
After finishing one job, setup your other jobs on CircleCI and then configure a workflow. This would essentially migrate your Build Chain.
Next, optimize your jobs with advanced features to see how much faster your builds could run on the CircleCI platform.
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.kts Equivalent CircleCI config.yml

TeamCity settings.kts	Equivalent 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!"`

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!'" } } })`

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!"`

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 Chain Equivalent CircleCI Workflow

TeamCity Build Chain	Equivalent 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`

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

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`

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.

Using Docker? Authenticating Docker pulls from image registries is recommended when using the Docker execution environment. Authenticated pulls allow access to private Docker images, and may also grant higher rate limits, depending on your registry provider. For further information see Using Docker authenticated pulls.

TeamCity Steps Equivalent CircleCI Steps

TeamCity Steps	Equivalent 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`

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

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" } } })`

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

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`

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.