Migrating a Linux Project from 1.0 to 2.0
This document will give you a starting place for migrating from CircleCI 1.0 to 2.0 by using a copy of your existing 1.0 configuration file and replacing the old keys with the new keys if equivalents exist.
- Steps to configure required keys
- Environment variables
- Steps to configure workflows
- Search and replace deprecated 2.0 keys
- Validate YAML
The migration process may not end with this document, but the goal is to get the majority of keys replaced with the equivalent syntax nesting and to help you get started with adding new functionality.
If you do not have a circle.yml
file, refer to the Sample 2.0 config.yml
File to get started from scratch.
Overview
CircleCI requires that you create a .circleci/config.yml
, and it adds new required keys for which values must be defined. Note: Parallelism may only be set in the .circleci/config.yml
file, the parallelism setting in the CircleCI app is ignored.
If you already have a circle.yml
file, the following sections describe how to make a copy of your existing file, create the new required keys, and then search and replace your 1.0 keys with 2.0 keys.
Using the 1.0 to 2.0 config-translation
endpoint
The config-translation
endpoint can help you quickly get started with converting a 1.0 config to 2.0. For more, see Using the 1.0 to 2.0 config-translation Endpoint.
Steps to configure required keys
-
Copy your existing
circle.yml
file into a new directory called.circleci
at the root of your project repository. -
Rename
.circleci/circle.yml
to.circleci/config.yml
. -
Add
version: 2
to the top of the.circleci/config.yml
file. - Add the following two lines to your
config.yml
file, after the version line. If your configuration includesmachine:
, replacemachine:
with the following two lines, nesting all of the sections of the old config file underbuild
.jobs: build:
- Add the language and version you want to run the primary container to your configuration using either the
docker:
and- image:
keys in the example or by settingmachine: true
or by usingmacos
. If your configuration includes language and version as shown forruby:
below, replace it as shown.ruby: version: 2.3
Replace with the following lines:
docker: - image: circleci/ruby:2.3-jessie auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
The primary container is an instance of the first image listed. Your job’s commands run in this container and must be declared for each job. See the Docker Getting Started if you are new to Docker containers.
machine: true
See the Using Machine section of the Choosing an Executor Type document for details about the available VM images.
macos: xcode: 11.3.0
- The
checkout:
step is required to run jobs on your source files. Nestcheckout:
understeps:
for every job by search and replacingcheckout: post:
With the following:
steps: - checkout - run:
For example:
checkout: post: - mkdir -p /tmp/test-data - echo "foo" > /tmp/test-data/foo
becomes
steps: - checkout - run: mkdir -p /tmp/test-data - run: echo "foo" > /tmp/test-data/foo
If you do not have a
checkout
step, you must add this step to yourconfig.yml
file. -
(Optional) Add the
add_ssh_keys
step with fingeprint to enable SSH into builds, see the Configuring CircleCI document for details. - Validate your YAML at http://codebeautify.org/yaml-validator to check the changes.
Environment variables
In CircleCI 2.0, all defined environment variables are treated literally. It is possible to interpolate variables within a command by setting it for the current shell.
For more information, refer to the CircleCI 2.0 document Using Environment Variables.
Steps to configure workflows
To increase the speed of your software development through faster feedback, shorter re-runs, and more efficient use of resources, configure workflows using the following instructions:
-
To use the Workflows feature, split your build job into multiple jobs, each with a unique name. It might make sense to start by just splitting out a deploy job to prevent you from having to re-run the entire build when only the deployment fails.
- As a best practice, add lines for
workflows:
,version: 2
and<workflow_name>
at the end of the master.circleci/config.yml
file, replacing<workflow_name>
with a unique name for your workflow. Note: The Workflows section of theconfig.yml
file is not nested in the config. It is best to put the Workflows at the end of the file because the Workflowsversion: 2
is in addition to theversion:
key at the top of theconfig.yml
file.workflows: version: 2 <workflow_name>:
-
Add a line for the
jobs:
key under<workflow_name>
and add a list of all of the job names you want to orchestrate. In this example,build
andtest
will run concurrently.workflows: version: 2 <workflow_name>: jobs: - build - test
-
For jobs which must run sequentially depending on success of another job, add the
requires:
key with a nested list of jobs that must succeed for it to start. If you were using acurl
command to start a job, Workflows enable you to remove the command and start the job by using therequires:
key.- <job_name>: requires: - <job_name>
-
For jobs which must run on a particular branch, add the
filters:
key with a nestedbranches
andonly
key. For jobs which must not run on a particular branch, add thefilters:
key with a nestedbranches
andignore
key. Note: Workflows will ignore job-level branching, so if you have configured job-level branching and then add workflows, you must remove the branching at the job level and instead declare it in the workflows section of yourconfig.yml
, as follows:- <job_name>: filters: branches: only: master - <job_name>: filters: branches: ignore: master
- Validate your YAML again at http://codebeautify.org/yaml-validator to check that it is well-formed.
Search and replace deprecated 2.0 keys
- If your configuration sets a timezone, search and replace
timezone: America/Los_Angeles
with the following two lines:
environment:
TZ: "America/Los_Angeles"
- If your configuration modifies $PATH, add the path to your
.bashrc
file and replace
environment:
PATH: "/path/to/foo/bin:$PATH"
With the following to load it into your shell (the file $BASH_ENV already exists and has a random name in /tmp):
steps:
- run: echo 'export PATH=/path/to/foo/bin:$PATH' >> $BASH_ENV
- run: some_program_inside_bin
- Search and replace the
hosts:
key, for example:
hosts:
circlehost: 127.0.0.1
With an appropriate run
Step, for example:
steps:
- run: echo 127.0.0.1 circlehost | sudo tee -a /etc/hosts
- Search and replace the
dependencies:
,database
, ortest
andoverride:
lines, for example:
dependencies:
override:
- <installed-dependency>
Is replaced with:
- run:
name: <name>
command: <installed-dependency>
- Search and replace the
cache_directories:
key:
cache_directories:
- "vendor/bundle"
With the following, nested under steps:
and customizing for your application as appropriate:
- save_cache:
key: dependency-cache
paths:
- vendor/bundle
-
Add a
restore_cache:
key nested understeps:
. -
Search and replace
deployment:
with the following, nested understeps
:
- deploy:
Validate YAML
When you have all the sections in .circleci/config.yml
we recommend that you check that your YAML syntax is well-formed using a tool such as http://codebeautify.org/yaml-validator. Then, use the circleci
CLI to validate that the new configuration is correct with regard to the CircleCI 2.0 schema. See the Using the CircleCI Command Line Interface (CLI) document for instructions. Fix up any issues and commit the updated .circleci/config.yml
file. When you push a commit the job will start automatically and you can monitor it in the CircleCI app.
Next Steps
- See the Tips for Migrating from 1.0 to 2.0
- Refer the Deploy document for examples of deployment.
- Refer to the Specifying Container Images document for more information about Docker and Machine images in CircleCI 2.0.
- Refer to the Configuring CircleCI document for details on the exact syntax of CircleCI 2.0
jobs
andsteps
and all available options.