NAV

Migrating from 1.0 to 2.0

Click here for Configuration Equivalents

Why Migrate from CircleCI 1.0 to 2.0?

While CircleCI 1.0 is a powerful CI/CD platform, it has some current limitations that make building software harder than it needs to be. This document explains some of those limitations and how they are addressed in CircleCI 2.0.

Native Docker Support

Although 1.0 does support Docker, it’s limited to older versions that don’t have access to Docker’s latest features.

This is because 1.0 uses LXC as a base container with a BTRFS file system. Recent versions of Docker don’t run properly in this environment, which means users can’t access Docker’s full featureset on 1.0.

In 2.0, if your job uses Docker, we’ll run your job on a dedicated VM so you can access all of Docker’s features.

Flexible Job Configuration

1.0 infers your project type and automatically runs the most suitable test and build commands. Running builds are divided into well-defined steps that are performed in order. For example, 1.0 always saves your dependency cache before running tests.

While this configuration can be powerful, there are some drawbacks. Maybe you want to disable inference. Or maybe you need to save the dependency cache after running tests since the tests themselves create more dependencies.

In 2.0, jobs are broken into granular steps. You can compose these steps within a job at your discretion. This gives you greater flexibility to run your build the way you want.

To learn more, please see the Configuration Reference.

Custom Build Image

In 1.0, you’re restricted to the build image CircleCI provides. In Linux builds, there are 2 images you can use: Ubuntu 12.04 and 14.04. While these images come with many languages and tools pre-installed, it’s frustrating if you need a version of a service or dependency that isn’t included.

Maybe you want to use a different version of MySQL than the one included in either default image. Installing another version adds time and complexity to your builds.

In 2.0, we support almost all public Docker images. You can also create a custom image and run jobs on that. You can even compose multiple images together (like MySQL 5.7 + Redis 3.2) and run jobs on them as if they were a single image.

To learn more, please see the Project Walkthrough.


Configuration Equivalents

CircleCI 2.0 introduces a completely new syntax in .circleci/config.yml. This article will help you convert your 1.0 circle.yml to a 2.0 config.yml.

Machine

Timezone

1.0

machine:
  timezone: Europe/Dublin

2.0

You can set the timezone in Docker images with the TZ environment variable. The value should be something like: TZ="/usr/share/zoneinfo/America/Los_Angeles". A full list of available timezone options is available on Wikipedia.

In your .circleci/config.yml it would look like:

version: 2
jobs:
  build:
    docker:
      - image: your/primary-image:version
      - image: mysql:5.7
        environment:
           TZ: "/usr/share/zoneinfo/America/Los_Angeles"
    working_directory: ~/your-dir
    environment:
      TZ: "/usr/share/zoneinfo/America/Los_Angeles"

Note that in the above example we are setting the timezone for both the primary image and an additional mySQL image.

Global Environment Variables

1.0

machine:
  environment:
    FOO: foo
    BAR: bar

2.0

version: 2
jobs:
  build:
    working_directory: /tmp
    docker:
      - image: busybox
    environment:
       FOO: foo
       BAR: bar

Modifying $PATH

1.0

machine:
  environment:
    PATH: "/path/to/foo/bin:$PATH"

2.0

In 2.0, interpolating variables into the environment is not yet supported.

As a workaround, you have to add it to your .bashrc then make sure your command shell loads it. We can also make sure it is loaded automatically by changing $BASH_ENV like so.

version: 2
jobs:
  build:
    working_directory: /tmp
    docker:
      - image: buildpack-deps:jessie
    environment:
       BASH_ENV: ~/.bashrc
  steps:
    run: echo 'export PATH=/path/to/foo/bin:$PATH' >> $BASH_ENV
    run: some_program_inside_of /path/to/foo/bin

In this example, we’ve added /path/to/foo/bin to the $PATH which will get evaluated when a command is executed. You can imagine that some_program_inside_of is an executable within that path, and we don’t need to refer to it by the full path name.

Languages

1.0

machine:
  ruby:
    version: 2.3

2.0

version: 2
jobs:
  build:
    working_directory: /tmp

    # In 2.0, we specify our Ruby version by using a public Docker image
    docker:
      - image: ruby:2.3

Hosts

1.0

machine:
  hosts:
    circlehost: 127.0.0.1

2.0

version: 2
jobs:
  build:
    working_directory: /tmp
    docker:
      - image: busybox

    steps:
      - run: echo 127.0.0.1 circlehost | tee -a /etc/hosts

Checkout

1.0

# 1.0
checkout:
  post:
    - git submodule sync
    - git submodule update --init # use submodules

2.0

version: 2
jobs:
  build:
    working_directory: /root/my-project
    docker:
      - image: phusion/baseimage
    steps:
      # Ensure your image has git and ssh (required by git to clone via SSH) so that CircleCI can clone your repo
      - run: apt-get -qq update; apt-get -y install git openssh-client

      # Checkout timing is no longer hardcoded, so this step can occur anywhere
      - checkout
      - run: git submodule sync && git submodule update --init # use submodules

Dependency/Database/Test

1.0

dependencies:
  override:
    - dependecy-install-command:
        timeout: 180

database:
  override:
    - setup-db-command

test:
  override:
    - test-command

2.0

The dependency, database, and test sections are translated into a sequence of run steps. To learn more about run steps, please checkout this page.

version: 2
jobs:
  build:
    working_directory: /root/my-project
    docker:

      # In 2.0, you can use multiple different images and group them as a 'Pod'.
      # Because Docker containers normally don't include DBs, you need to bring
      # a build image that serves as DB container in your build.
      - image: primary-build-image
      - image: db-image-1
      - image: db-image-2

    steps:
      - checkout

      # We're still building our new inference system for 2.0, but until then, there’s nothing to override.
      # For now, you'll need to manually install your project’s dependencies.
      # The current timeout for no output is hardcoded to 600 seconds
      - run:
          name: Install Dependencies
          command: dependency-install-command

      # The DB is not automatically created in 2.0, so we manually set up a test DB
      - run:
          name: Create Test DB
          command: setup-db-command

      # Again, no inference in 2.0 yet, so nothing to override here, either.
      # Just use any test commands.
      - run:
          name: Run Tests
          command: test-command

Caching

Cache Directories

1.0

dependencies:
  override:
    - bundle install --path vendor/bundle:
        timeout: 180

  cache_directories:
    - "vendor/bundle"

2.0

version: 2
jobs:
  build:
    working_directory: /root/my-project
    docker:
      - image: ruby:2.3

    steps:
      - checkout
      - run: bundle install --path vendor/bundle

     # Caching is fully customizable in 2.0
     - save_cache:
        key: dependency-cache-{{ checksum "Gemfile.lock" }}
        paths:
          - vendor/bundle

Please note that you need to have a restore cache step by yourself in 2.0. There are also lots of cache prefix options available.

Read about them in Configuration Reference.

Deployment

1.0

deployment:
  staging:
    branch: master
    heroku:
      appname: foo-bar-123

2.0

Currently, 2.0 doesn’t support automatic deployment via integrations (like the above Heroku example).

You can write your own manual deploy steps as shown in the Configuration Reference.

If you add SSH keys via the CircleCI UI ‘Project Settings > SSH Permissions’ screen for deployment with 2.0, you must explicitly add them to your job with: - add_ssh_keys in .circleci/config.yml. See Configuration Reference add SSH keys. The documentation also explains how to activate ssh-agent so that you can ssh-add your keys for tools that require them to be available via an agent.