Circle CI is quickly becoming my favorite CI tool. Their infrastructure is pretty robust - I have yet to see a test flake out. Plus, their UI is elegant, their config files are more expressive than Travis', and their free tier generously includes support for private builds for teams. I still have a soft spot in my heart for Semaphore, but I find it hard to use them because they charge extra for organizations and they require you to configure your environment in a web UI rather than in a YAML file. Both are leaps and bounds ahead of Travis and Shippable: their infrastructures are flakier than a Head & Shoulders commercial.
Here's a summary of the benefits of Circle CI over Semaphore, Travis, and Shippable:
- Robust architecture (as opposed to Shippable and Travis)
- Configure with a
.ymlfile in your repo (as opposed to Semaphore)
- Free for private repos and organizations - only pay when you want parallel builds (as opposed to Travis and Semaphore)
Now that you see why Circle CI is so useful, let's take a look at how to set up Circle CI for a Node.js project.
Adding a Project to Circle
Once you register for an account and log in, you should see an 'Add Projects' button on the left hand side of your Circle dashboard.
Next, choose the GitHub organization that your project is in:
Then choose the project you want to build and hit "Build Project" to trigger
your first build for this project. In this example, I'll be adding my
MongoDB test fixture preprocessor called dookie
to Circle CI. This project's test setup is not unusual for a node project -
npm install to install all the dependencies, start MongoDB, and run
Once you hit "Build Project", Circle will kick off the first build of your
project. Circle prides themselves on being able to infer the right configuration
for your project, but in my experience they always get it wrong. The
initial build of dookie crashes
horribly because Circle uses node 0.10 by default and is
not smart enough to see
"node": ">= 4.0.0" in the
If your initial build fails, don't worry, you can configure Circle from a
Note: By default, Circle creates a GitHub deploy key for your repo. You can think of a deploy key as an SSH key that only works for that repo. This means that, by default, Circle only gets access to one of your repos, not all of them.
TLDR; see a diff on GitHub
circle.yml file in your repo's root directory tells Circle how
to set up and test your project. Circle has a
detailed guide to all the options available for
but in this article I'll highlight a few basic ones that are important for
The first option is the Node.js version. Circle uses Node.js 0.10 by default,
which may not be the right choice for your project. You can always tell Circle
to download node directly from nodejs.org, but Circle also
pull the Node.js version you specify in the
# Circle will use node v4.0.0
circle.yml file is broken up into 6 "sections" or "phases". The "machine"
phase is the first phase: it's responsible for setting up the core VM. There's
also a "database" phase. Much like Travis, Circle uses 3-year-old MongoDB 2.4
by default, which is not ideal. However, it's easy to install whichever
version of MongoDB you want in the "database" phase. Let's run MongoDB 3.2.3:
# Circle will execute the below commands
# Stop MongoDB
- sudo service mongodb stop
# Download MongoDB 3.2.3
- curl -Ol https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-ubuntu1204-3.2.3.tgz
# Untar it
- tar -zxvf mongodb-linux-x86_64-ubuntu1204-3.2.3.tgz
# Create data directory
- mkdir -p ./data/db
# Fork MongoDB and log to './mongod.log'. Print the log file if it failed.
- ./mongodb-linux-x86_64-ubuntu1204-3.2.3/bin/mongod --dbpath ./data/db --logpath ./mongod.log --fork || cat ./mongod.log
You can also install MongoDB in the "machine" phase. I'm not sure which approach is more correct, but as far as I can tell these approaches are interchangeable.
The most important phase is the "test" phase, which is where you define how
to run your repo's tests. Circle is smart enough to know to run
for Node.js projects, but if you want to override this
(or you just want to be explicit) you can
- npm test
You can check out the whole
circle.yml for dookie on GitHub.
Circle is an excellent CI for teams. It's robust, extensible, and fits great with any GitHub-centric Node.js workflow. Circle is free for public as well as private projects, so now your team has no excuse to not run tests on every commit.