Configuring CircleCI

CircleCI automatically infers your settings from your code, so CircleCI’s normal processing works just fine in most circumstances. When it doesn’t, the circle.yml file makes it easy to tell CircleCI what you need. This is a simple YAML file where you spell out any tweaks required for your app. You place the file in your git repo’s root directory and CircleCI reads the file each time it runs a build.

If you want a quick look at how to set up your circle.yml file, check out our sample file.

Should you have a test failure, our troubleshooting section can likely tell you the best way to solve the problem. If you find yourself repeatedly consulting this guide, please contact us and let us know what you’re working on. We’ll try to make it easier for you.

File structure and content

The circle.yml file is made up of six primary sections. Each section represents a phase of running your tests:

  • machine: adjusting the VM to your preferences and requirements
  • checkout: checking out and cloning your git repo
  • dependencies: setting up your project’s language-specific dependencies
  • database: preparing the databases for your tests
  • test: running your tests
  • deployment: deploying your code to your web servers

The circle.yml file contains another general section for general build-related configurations that are not related to a specific phase, and an experimental section for early access previews of configuration changes under consideration.

Remember: most projects won’t need to specify anything for many of the phases.

The sections contain lists of bash commands. If you don’t specify commands, CircleCI infers them from your code. Commands are run in the order they appear in the file; all test commands are run to completion, but a non-zero exit code during the setup sections (machine:, checkout:, dependencies:, database:) will cause the build to fail early. You can modify which—and when—commands are run by adding override, pre and/or post to adjust CircleCI’s inferred commands. Here’s how it works:

  • pre: commands run before CircleCI’s inferred commands
  • override: commands run instead of CircleCI’s inferred commands
  • post: commands run after CircleCI’s inferred commands

Each command is run in a separate shell. As such, they do not share an environment with their predecessors, so be aware that export foo=bar in particular does not work. If you’d like to set an environment variable globally, you can specify them in the Machine configuration section, described below.


You can tweak individual commands by adding a modifier. Allowed modifiers are:

  • timeout: if a command runs this many seconds without output, kill it (default:600s)
  • pwd: run commands using this value as the current working directory (default: the checkout directory named for your project, except in the machine and checkout/pre sections, where it defaults to $HOME.)
  • environment: a hash creating a list of environment variables set for this command (see Machine configuration for this modifier’s properties when used in the machine section of the file)
  • parallel: (only used with commands in the test section) if you have manually set up parallelism, set this to true to run a command across all VMs
  • files: The files identified by the file list (or globs) will be appended to the command arguments. The files will be distributed across all containers running the build. Check manual parallelism setup document for more details.
  • background: when “true”, runs a command in the background. It is similar to ending a shell command with ‘&’, but works correctly over ssh. Useful for starting servers, which your tests will connect to.

Note that YAML is very strict about indentation each time you add a new property. For that reason, modifiers must be indented one level from their command. In the following example, we treat the bundle install command as a key, with timeout, environment, and pwd as the command’s hash values. This means you will need to add a colon to the end of the command for it to parse correctly.

Important note: modifiers are double indented, so four spaces instead of two. (This is probably the cause if you get an error like Syntax Error while parsing circle.yml: mapping values are not allowed here...)

    - bundle install: # note the colon here
        timeout: 240 # note the double indentation (four spaces) here
          foo: bar
          foo2: bar2

Machine configuration

The machine section enables you to configure the virtual machine that runs your tests.

Here’s an illustration of the types of things you might typically set in the machine section of the file.

    version: 1.9.3-p0-falcon

    - bundle exec rake custom:test:suite

This example sets the time zone, chooses a Ruby version and patchset, and adds a custom test command to run after the rest of your commands.

Although pre and post are supported in the machine section, override is not. Note that custom environment variables are not available during the machine pre section because they are setup in the main machine section.

Here’s how you might adjust the circle.yml file using pre to install a different version of phantomjs than the version CircleCI has installed.

    - curl -k -L -o phantomjs.tar.bz2
    - tar -jxf phantomjs.tar.bz2


You set environment variables for all commands in the build by adding environment to the machine section. Remember that CircleCI uses a new shell for every command; as previously mentioned export foo=bar won’t work. Instead, you must include something like this.

    foo: bar
    baz: 123

If you don’t want to use this method, there are a number of other options.


The machine’s time zone is UTC by default. You use timezone to adjust to the same time zone as your production server. Changing the time to your development machine’s time zone is problematic.

This modifier tells CircleCI to overwrite /etc/timezone and then restart all databases and services that rely on it. This modifier supports any time zone listed in the IANA time zone database. You can find this by looking in /usr/share/zoneinfo/ on your Unix machine or in the TZ column in Wikipedia’s list of TZ database time zones.

Be aware that some developers, especially those that collaborate across different time zones, do use UTC on their production servers. This alternative can avoid horrific Daylight Saving Time (DST) bugs.


Sometimes you might need to add one or more entries to the /etc/hosts file to assign various host names to an IP address. You can provide a mapping from hostnames to IP addresses in the following manner:


CircleCI will automatically update the /etc/hosts file with these values. Hostnames must be well formed. CircleCI will only accept hostnames that contain alpha-numeric characters, hyphens (-) and dots (.).

Ruby version

CircleCI uses RVM to manage Ruby versions. We use the Ruby version you specify in your .rvmrc, your .ruby-version file, or your Gemfile. If you don’t have one of these files, we’ll use default version of Ruby. Please check out Ubuntu 12.04 and Ubuntu 14.04 pages to find out which version is the default.

If you use a different Ruby version let CircleCI know by including that information in the machine section. Here’s an example of how you do that.

    version: 1.9.3-p0-falcon

Node.js version

CircleCI uses NVM to manage Node versions. Pre-installed versions can be found on the Ubuntu 14.04 (default) and Ubuntu 12.04 pages respectively.

Here’s an example of how to set the version of Node.js to be used for your tests.

    version: 0.11.8

Java version

Here’s an example of how to set the version of Java to be used for your tests.

    version: openjdk7

You can find more details about supported versions for Ubuntu 14.04 (default) and Ubuntu 12.04.

PHP version

CircleCI uses php-build and phpenv to manage PHP versions. Here’s an example of how to set the version of PHP used for your tests:

    version: 5.4.5

You can find more details about supported versions for Ubuntu 14.04 (default) and Ubuntu 12.04.

Python version

CircleCI uses pyenv to manage Python versions. Here’s an example of how to set the version of Python used for your tests.

    version: 2.7.5

You can find more details about pre-installed versions for Ubuntu 14.04 (default) and Ubuntu 12.04.

GHC version

  version: 7.8.3

You can find more details about supported versions here.

Other languages

We also support other languages including Clojure, C/C++, Golang, and Erlang.

Pre-installed versions are different depending on which build image you are using.

Please check out Ubuntu 12.04 build image and Ubuntu 14.04 build image to find out what versions are supported.

Databases and other services

CircleCI supports a large number of databases and other services. Most popular ones are running by default on our build machines (bound to localhost), including Postgres, MySQL, Redis (not started by default on Ubuntu 14.04) and MongoDB.

You can enable other databases and services from the services section:

    - cassandra
    - elasticsearch
    - rabbitmq-server
    - redis
    - riak
    - beanstalkd
    - couchbase-server
    - neo4j
    - sphinxsearch

Code checkout from GitHub or Bitbucket

The checkout section is usually pretty vanilla, but we include examples of common things you might need to put in the section. Because we don’t read circle.yml until after the checkout phase, only post is supported in this section.

Example: using git submodules

    - git submodule sync
    - git submodule update --init

Example: overwriting configuration files on CircleCI

    - mv config/.app.yml config/app.yml

Project-specific dependencies

Most web programming languages and frameworks, including Ruby’s bundler, npm for Node.js, and Python’s pip, have some form of dependency specification; CircleCI automatically runs commands to fetch such dependencies.

You can use override, pre, and/or post to modify dependencies commands. Here are examples of common tweaks you might make in the dependencies section.

Example: using npm and Node.js

    - npm install

Example: using a specific version of bundler

    - gem uninstall bundler
    - gem install bundler --pre

Bundler flags

If your project includes bundler (the dependency management program for Ruby), you can include without to list dependency groups to be excluded from bundle install. Here’s an example of what that would look like.

    without: [production, osx]

Custom Cache Directories

CircleCI caches dependencies between builds. To include any custom directories in our caching, you can use cache_directories to list any additional directories you’d like cached between builds. Here’s an example of how you could cache two custom directories.

    - "assets/cache"    # relative to the build directory
    - "~/assets/output" # relative to the user's home directory

Caching happens after the dependency step, so the directories that are specified in cache_directories must be available before then.

Caches are private, and are not shared with other projects.

Database setup

Your web framework typically includes commands to create your database, install your schema, and run your migrations. You can use override, pre, and/or post to modify database commands. See Setting up your test database for more information.

If our inferred database.yml isn’t working for you, you may need to override our setup commands (as shown in the following example). If that is the case, please contact us and let Circle know so that we can improve our inference.

    - mv config/ config/database.yml
    - bundle exec rake db:create db:schema:load --trace

FYI, you have the option of pointing to the location of your stored database config file using the environment modifier in the machine section.

    DATABASE_URL: postgres://ubuntu:@

Running your tests

The most important part of testing is actually running the tests!

CircleCI supports the use of override, pre, and/or post in the test section. However, this section has one minor difference: all test commands will run, even if one fails. This allows our test output to tell you about all the tests that fail, not just the first error.

Example: running spinach after RSpec

    - bundle exec rake spinach:
          RAILS_ENV: test

Example: running phpunit on a special directory

    - phpunit my/special/subdirectory/tests

CircleCI also supports the use of minitest_globs (a list of file globs, using Ruby’s Dir.glob syntax) that can list the file globs to be used during testing.

By default, when testing in parallel, CircleCI runs all tests in the test/unit, test/integration, and test/functional directories. You can add minitest_globs to replace the standard directories with your own. This is needed only when you have additional or non-standard test directories and you are testing in parallel with MiniTest.

Example: minitest_globs

    - test/integration/**/*.rb
    - test/extra-dir/**/*.rb


The deployment section is optional. You can run commands to deploy to staging or production. These commands are triggered only after a successful (green) build.

    branch: production
      - ./
    branch: master
      - ./

The deployment section consists of multiple subsections. In the example shown above, there are two—one named production and one named staging. Subsection names must be unique. Each subsection can list multiple branches, but at least one of these fields must be named branch. In instances of multiple branches, the first one that matches the branch being built is the one that is run. In the following example, if a developer pushes to any of the three branches listed, the script is run.

    branch: [dev_alice, dev_bob, dev_carol]
      - ./

The branch field can also specify regular expressions, surrounded with / (e.g. /feature_.*/):

    branch: /feature_.*/
      - ./

You can also optionally specify a repository owner in any deployment subsection. This can be useful if you have multiple forks of the project, but only one should be deployed. For example, a deployment subsection like this will only deploy if the project belongs to “circleci”, and other users can push to the master branch of their fork without triggering a deployment:

    branch: master
    owner: circleci
      - ./

Note The deployment section doesn’t support sub-sections such as pre that you might find elsewhere in circle.yml. If you get a strange error such as “commands must be a list” when in the deployment section, this is likely the issue.


In addition to deploying based on branch, you can deploy based on tags.

Normally, pushing a tag will not run a build. If there is a deployment configuration with a tag property that matches the name of the tag you created, we will run the build and the deployment section that matches.

Cutting a release on GitHub creates a tag and follows the same rules.

In the below example, pushing a tag named release-v1.05 would trigger a build & deployment. Pushing a tag qa-9502 would not trigger a build.

    tag: /release-.*/
    owner: circleci
      - ./

Note: change owner from circleci to the username or organization that the repo belongs to or your build won’t run.

Similar to the branch property, the tag property can be an exact string or regex. It can also be a list of exact matches or regexes.

A popular convention is to create tags like v1.2.3 for the 1.2.3 version of your software. The following regex will implement that pattern:


v1, v1.2, and v1.2.3 (and so on) all match.

SSH Keys

If deploying to your servers requires SSH access, you’ll need to upload the keys to CircleCI. CircleCI’s UI enables you to do this on your project’s Project Settings > SSH keys page. Add and then submit the one or more SSH keys needed for deploying to your machines. If you leave the Hostname field blank, the private key will be used for all hosts.


CircleCI also has first-class support for deploying to Heroku. Specify the app you’d like to git push to under appname. Upon a successful build, we’ll automatically deploy to the app in the section that matches the push, if there is one.

    branch: master
      appname: foo-bar-123

Setting up our deployment to Heroku requires one extra step. Due to Heroku’s architecture and security model, we need to deploy as a particular user. A member of your project, possibly you, will need to register as that user. CircleCI’s UI enables you to do this on your project’s Project Settings > Heroku settings page.

Heroku with pre or post-deployment steps

If you want to deploy to Heroku and also run commands before or after the deploy, you must use the ‘normal’ deployment syntax.

    branch: production
      - git push $CIRCLE_SHA1:master
      - heroku run rake db:migrate --app foo-bar-123


CircleCI sends personalized notifications by email.

In addition to these per-user emails, CircleCI sends notifications on a per-project basis.

CircleCI supports sending webhooks when your build completes. CircleCI also supports Slack, HipChat, Campfire, Flowdock and IRC notifications; you configure these notifications from your project’s Project Settings > Notifications page.

This example will POST a JSON packet to the specified URL.

    # A list of hook hashes, containing the URL field
    - url:

The JSON packet is identical to the result of the Build API call for the same build, except that it is wrapped in a “payload” key:

  "payload": {
    "vcs_url" : "",
    "build_url" : "",
    "build_num" : 22,
    "branch" : "master",

There is also an experimental setting you can configure to specify black- or white-listing of branches you want to get chat channel build notifications for in the per branch build notification section.

Specifying branches to build

CircleCI by default tests every push to any branch in the repository. Testing all branches maintains quality in all branches and adds confidence when the branches are to be merged with default branch.

You may, however, blacklist branches from being built in CircleCI. This example excludes gh-pages from being built in circle:

      - gh-pages # list of branches to ignore
      - /release\/.*/ # or ignore regexes

You may also whitelist branches, so only whitelisted branches will trigger a build. This example limit builds in circle to master and feature-.* branches:

      - master # list of branches to build
      - /feature-.*/ # or regexes

We discourage branch whitelisting, it means work-in-progress code can go a long time without being integrated and tested and we’ve found it leads to problems when that untested code gets merged.

circle.yml is per-branch configuration file, and the branch ignore list in one branch will only affect that branch and no other one.

Specifying build directory

Circle runs all commands on the repository root, by default. However, if you store your application code in a subdirectory instead of the root, you can specify the build directory in circle.yml. For example, to set the build directory to api sub-directory, you can use the following configuration:

  build_dir: api

Circle will run its inference as well as all build commands from that directory.

Specifying custom artifacts directories and files

You can specify directories and files (in addition to the default $CIRCLE_ARTIFACTS directory) to be saved as artifacts:

    - "selenium/screenshots" # relative to the build directory
    - "~/simplecov" # relative to the user's home directory
    - "test.txt" # a single file, relative to the build directory

If you require more complex artifact handling such as wildcards, it’s recommended to move your artifacts into the $CIRCLE_ARTIFACTS directory.

    - mkdir $CIRCLE_ARTIFACTS/json_output
    - mv solo/target/*.json $CIRCLE_ARTIFACTS/json_output

Experimental configuration

Our experimental section is a way of giving early previews of new configuration options we are considering adding. These settings are liable to change without notice.

Per branch build notification in chat channels

The only experimental setting available at this time is a black- and white-list mechanism for chat channel build notifications based on the branch name.

The behavior of the “ignore” and “only” settings is the same as the black- and white-listing of branches to build in the Branches section. Each setting takes a list of either strings or regexes; regexes are specified with ‘/’ around the value.

The following configuration will suppress any chat channel build notifications for any build of a branch whose name starts with “dev” or “experiment”, or which is named “sandbox”:

        - /dev.*/
        - /experiment.*/
        - sandbox

Alternatively, you can only send notifications for branches which match a whitelist. The following config will only send notices for the master branch and any branch starting with “feature”:

        - master
        - /feature-.*/

You can combine them, in which case only branch names which do match the whitelist and do not match the blacklist get notifications. So for:

        - /feature.*/
        - /feature\.experiment.*/

a branch named “feature-1” will send a notification, but “feature.experiment-1” will not.

Need anything else?

We are adding support for configuring every part of your build. If you need to tweak something that isn’t currently supported, please contact us and we’ll figure out how to make it happen.