Getting started with CircleCI

This guide assumes that you have a GitHub account and a GitHub repository that you want to target for continuous integration. You'll need both of these things if you're following along with the guide, but if you're just here for an overview, carry on.

The easiest way to create your account is to sign up using your GitHub account. So go to the home page at https://circleci.com and click on "Sign Up".

Then on the next page click "Start with GitHub"

The UI for this step is currently being changed, but I will describe conceptually what this step entails. A "project" is basically a single code repository. So since you signed up with your GitHub account, you'll need to locate the repository that you want to target and click "Setup project".

You'll be taken to a view where you can configure your project. Here you can choose details like OS, language, and which version of Circle you want to use. For this option, choose Circle 2.0.

Here you'll also find instructions for configuring your repository to work with CircleCI.

A this point you can click "Start building", we'll configure the repository in the following steps.

Setting up your repository is fairly simple. As long as the configuration file exists, Circle will run your integration.

So let's add the file. For Circle 2.0, you need to create a folder called .circleci and add a file called config.yml.

mkdir .circleci
touch .circleci/config.yml

Once this is done we'll add some basic configuration.

Let me begin this step by saying that any useful configuration that you will need is going to be specific to your app. This includes things like building docker images, running unit tests, etc. So I won't be able to provide specifics in this guide for how to accomplish those things, but fortunately the CircleCI docs are adequate.

So we will start with a shell of a config, a sort of "hello world", if you will.

Add the following to the config.yml file you just created.

version: 2
jobs:
  build:
    docker:
      - image: python:3.5
    working_directory: /code
    steps:
        - checkout
        - run:
            name: Hello world
            command: echo "Hello world"

Let me explain a little bit about what is going on here.

First, the job will be run inside of a docker container. So in the "docker" section we are simply specifying the image that we want to use.

Next, we specify the working directory. For our purposes, this is just an arbitrary directory where the code will be checked out and tests are run.

Next, are the steps. Here is where we'll do all of the important work like building, testing, shipping, etc. But for our simple example, we're just going to checkout the code, and echo "Hello world".

So add this configuration and save the file.

Note: If you're application is built using docker, this can be confusing. You'll want to read up on the notion of a primary container and remote docker.

Now add your file, commit your code, and push.

git add .
git commit -m "added circle config"
git push origin <branch-name>

Now move over to the CircleCI dashboard, and click on "Builds".

You should see your build added to the top of the list, and it should have a status of "Running". Since we don't have many steps, this will probably build very quickly and the status should soon be changed to "Success".

Click on the build to view details. Here you can see things like how long the build took, the steps that were run, and any resources that were used.

So far we've created a CircleCI account, set up our project, and configured our code run the integration. So at this point, it's time for you to dive into the docs and start adding some more steps.