CircleCI + GitHub + Heroku = deployed green builds in minutes

Editor's note: Paul Biggar is CEO at CircleCI. He is a Y Combinator alumnus and holds a PhD in Computer Science with a focus on static analysis of scripting languages.

Why Continuous Integration is useful

Continuous Integration, and its cousin, Continuous Delivery, are some of the best ways to increase the productivity of your dev team. As well as reducing project risk, a more productive team is happier, and leads to happier customers too. Developers are unhappy when they're not shipping code. A slow development cycle saps their energy, damages their morale, and removes the joy of a job well done. They feel worse, they enjoy their job less, and their performance suffers even more. Continuous Integration provides the ability to move quickly. When failing tests creep into a code base, developers waste time hunting them down. Those failing test also make people ignore the test suite, leading to site unreliability. CI prevents this. By creating an automated process for code shipping to customers, Continuous Delivery also makes developers more productive, and happy to see their code ship as soon as possible. Naturally, this delights customers too: imagine if a customer tells you about a bug, only to see it fixed 10 minutes later. Contrast this to a customer who sees their bug still hasn't been fixed after two weeks: much less delightful. <!--more-->

The birth of CircleCI

Before CircleCI, I worked on the Firefox Javascript engine at Mozilla. We had an internal CI system called Tinderbox, and everytime you pushed code it ran about 100 hours of tests on various platforms. I hated Tinderbox, because it wasn't a very good product. It provided the absolute minimum required for a CI system, but it wasn't designed by people who used it every day. I spent a year thinking "if I was in charge, I would build it differently". When I decided to leave Mozilla, I had spent a year thinking about how to buid an amazing CI service that developers would love to use. Some of the core features of CircleCI, like being able to SSH into the build VMs to debug failing tests, or providing real-time updating build output, came directly from this experience I had. Allen, my Co-Founder, had a similar revelation. He had been tech lead for five projects, where he had tried to set up old CI tools, like Bamboo and TeamCity. He was annoyed by how difficult it was to set them up and to use them, and to consistently ship code quickly to customers. When we started CircleCI, Allen's first features were to make it trivial to set up and to deploy to customers on a successful build. Today, Circle has run over 2 million builds and over 100 million tests. Our customers include Kickstarter, Red Bull and Shopify, and we have a large number of customers of all sizes, all the way from giant Fortune 500s to two-person startups. One of the main benefits of using Circle over other solutions is that it's super easy to get started. In this post, we'll show you how in a few quicks steps.

How to get up and running

Runnning your tests

We designed CircleCI to be really easy to set up. Our hosted build infrastructure allows you to test a wide variety of projects. We support dozens of versions of Ruby, Python, Node and PHP, along with Java, Go, Clojure, Scala, C and C++. We also support dozens of DBs and queues, from Postgres to Couch, and browsers and headless browserslike, Chrome, Firefox, PhantomJS, and others. We integrate tightly with GitHub, so once you approve and select a project we can automatcally test every push and Pull Request. Our setup algorithms will automatically detect how to run your code by inspecting it, and can start to test within 10s of signing up.


  1. Visit
  2. Click signup, which takes you to the GitHub permissions page
  3. Approve the permissions on GitHub
  4. Select a project to test from the list

With those steps, your first test will begin to run in real-time.


In some cases, your project might not be so easy to infer, or might fail because it needs a custom step. We have a simple process to fix that: add a circle.yml file to your repo that allows you customize any part of the build (you can also tweak it from our UI, if you don't want to change your repo). You can run extra commands, start services or daemons, install new libraries or set up deployment. You can also split your tests across multiple machines; if you have a long test suite, you can run it up to 64x faster!

Deploying to Heroku

To take advantage of Contiunous Delivery, you can set CircleCI up to automatically deploy your code, if it passes tests on the master branch. You may wish to deploy to a staging branch first, or to deploy directly to customers. Either one is possible on CircleCI. We support many different deployment targets, and have customers deploying to Heroku, Engineyard, AWS, DotCloud, and many others

We'll focus on Heroku here:

From your project page on CircleCI, choose Edit settings > Heroku settings and do the following:

  1. Add a Heroku API key; this allows CircleCI create a Heroku deploy key
  2. Appoint yourself as the Heroku Deploy User (this tells us to deploy this project as you)
  3. Add deployment settings to your circle.yml file. For example
        branch: master
          appname: mystagingapp

After this setup, we'll deploy to your application (in this case "mystagingapp") every time your tests pass on the master branch. You can also set up more complicated commands to deploy to Heroku or for any other deployment (check out our documentation for more details).

It's easy to get started, try it now at