Setting up continuous integration with GitHub
Tags: devops, github, circleci, tutorial
Published: 2018-09-18 17:51:49

---
title: Setting up continuous integration with GitHub
published: true
tags: devops, github, circleci, tutorial
canonical_url: https://circleci.com/blog/setting-up-continuous-integration-with-github/
---

_This article was originally posted on CircleCI's [blog][15] by Stanley Ndagi_

***

[Continuous Integration (CI)][14] involves the test automation of feature branches before they are merged to the main Git branch in a project. This ensures that a codebase does not get updated with changes that could break something. Continuous Delivery (CD), on the other hand, builds upon CI by automating releases of these branches and/or the main branch. This allows small incremental updates to reach your users faster, in line with Agile software development philosophy.

In this article, I will take you through setting up CI with GitHub. We will use a Python application to demonstrate our CI pipeline.

<!-- more -->

Here are the steps we will take:

1. Create a simple Python application (with Flask)
2. Create tests for this app
3. Add the `config.yml` file
4. Push to GitHub
5. Configure CircleCI
6. Update our `README` with a badge
7. Create a PR and see CircleCI in action

## Creating a simple Python app

#### Prerequisites

If you don’t have Python installed, follow the instructions [here][1] for your local system. The Python installation comes with `pip` (The PyPA recommended tool for installing Python packages).

#### Building the app

For simplicity, in terms of fewest lines of code, we will create a Flask application. Flask is a microframework for Python. For our exercise, little knowledge of the framework is necessary. We’ll use the example found [here][2].

First, create a project directory (folder) and `cd` into it. Type this into Terminal:

```bash
mkdir python_app && cd $_/
```

Next, open your favorite editor and create a `hello.py` file. Then, copy the following lines into that file:

```python
from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World!"
```

#### Virtual environments in Python

When working in Python, it is strongly advised that you use a virtual environment. This allows you to install Python packages in an abstracted environment that is not your entire local machine. Some common ways to do this are to use [`virtualenv`][3] or, even better, [`virtualenvwrapper`][4]. We’ll use the module `venv` that comes as a part of Python3. This is how it’s done:

* Create the virtual environment: 

```bash
python3 -m venv venv
```

(Note that we can use other names for our virtual environment, like in the next example.) 

```bash
python3 -m venv Env
```

* Activate this environment: 

```bash
source venv/bin/activate
```

(Replace _venv_ if you used another name for the environment)

You will notice `(venv)` just before the shell prompt telling you that the virtual environment is active. Any Python package that is installed will be installed within this environment. To deactivate this environment simply run:

```bash
deactivate
```
#### Running the app

Now, let’s create a `requirements.txt` file in our editor. Add the word `Flask` to the file and save it.

```
Flask




```

Then, within the virtual environment, install the package by running:

```bash
pip install -r requirements.txt
```

The final command to run this application is:

```bash
FLASK_APP=hello.py flask run
```

You can see the application running on your browser at [http://localhost:5000/][5].

## Tests

In your editor, create a `tests.py` file and paste these lines into it:

```python
from hello import app
with app.test_client() as c:
    response = c.get('/')
    assert response.data == b'Hello World!'
    assert response.status_code == 200
```

Please see these references for more information on tests:
* [http://flask.pocoo.org/docs/1.0/testing/][6]
* [https://damyanon.net/post/flask-series-testing/][7]

Now, let’s run our test. Open Terminal and run:

```bash
python3 tests.py
```

Nothing should be returned to our Terminal. Why? The reason is that we structured our Flask app so that it does not output to Terminal on a pass. This means that our tests are passing. The resources mentioned above give better examples of Terminal UX (user experience) on tests passing and failing, but this will suffice for our case.

## CircleCI config file

Create a `.circleci` folder and inside of that create a [`config.yml`](https://circleci.com/docs/2.0/sample-config/) file. Then, copy these lines into it:

```yaml
version: 2
jobs:
  build:
    docker:
      - image: circleci/python:3.6
    steps:
      - checkout
      - restore_cache:
          key: deps1-{{ .Branch }}-{{ checksum "requirements.txt" }}
      - run:
          command: |
            python3 -m venv venv
            . venv/bin/activate
            pip install -r requirements.txt
      - save_cache:
          key: deps1-{{ .Branch }}-{{ checksum "requirements.txt" }}
          paths:
            - "venv"
      - run:
          name: Running tests
          command: |
            . venv/bin/activate
            python3 tests.py
      - store_artifacts:
          path: test-reports/
          destination: python_app
```

For more information regarding this `config` file, see: [https://circleci.com/docs/2.0/language-python/][8].

## Pushing to GitHub

We should have initialized Git earlier and had atomic commits (the philosophy of committing your code early and often). However, since this tutorial is about integration of CircleCI and GitHub, I intentionally put it on hold until now.

Our current code structure looks like this:

![2018-09-11-Stanley01.png](https://thepracticaldev.s3.amazonaws.com/i/oicdlnc7jv92m3u3rocv.png)

Open your editor and create a `.gitignore` file in the working directory to state which files and folders that we _don’t_ want to commit to Git. Copy the following lines into that file:

```
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]

# Virtualenv
venv/*

```

We are now going to commit our code by running the following commands:
```bash
git add .
```
```bash
git commit -m "Initial commit"
```

Go to [https://github.com][9] and create a GitHub account, if you don’t already have one. Then, create a repository.

![2018-09-11-Stanley02.png](https://thepracticaldev.s3.amazonaws.com/i/cokim8dy78eet3ejzp0g.png)

![2018-09-11-Stanley03.png](https://thepracticaldev.s3.amazonaws.com/i/rw9mlh7qgc8fbggkn8r9.png)

After creating your new repository, you will get to a page like this one:

![2018-09-11-Stanley04.png](https://thepracticaldev.s3.amazonaws.com/i/i36fkx81mia51u3w2bx8.png)

We’ll go with the second option, <strong>…push an existing repository</strong>. Run:

```bash
git remote add origin https://github.com/NdagiStanley/python_app.git
git push -u origin master
```

## Configuring CircleCI

Now that the repo is on GitHub, we can finalize the CI by configuring CircleCI.

Head on over to [https://circleci.com/][10]. Then click **Sign Up** at the top right.

![2018-09-11-Stanley05.png](https://thepracticaldev.s3.amazonaws.com/i/djn0jkk1dt7gghfwcjwx.png)

Sign up for CircleCI with your GitHub account.

![2018-09-11-Stanley06.png](https://thepracticaldev.s3.amazonaws.com/i/kx77jzo1rkyxronku8bo.png)

Once you are logged in, ensure that your personal GitHub account is active. If you are in several GitHub organizations, one of them might be active. Just click the drop down menu (top left) and select your GitHub username. Then, click **Add Projects**. The most recent project, ‘python_app’, appears there.

![2018-09-11-Stanley07.png](https://thepracticaldev.s3.amazonaws.com/i/uuief10r77yulxmslqa7.png)

Click **Set up Project** at the right side of the row that includes our project. On the redirected page, you’ll notice the **Next Steps** section. Had we not had our own `.circleci/config.yml` file, we would have started at **No. 1**. We just need to scroll to **No. 5** and click **Start building**.

![2018-09-11-Stanley08.png](https://thepracticaldev.s3.amazonaws.com/i/ygu0aifdhfybsgxukele.png)

Within no time, the build passes. It's successful!

![2018-09-11-Stanley09.png](https://thepracticaldev.s3.amazonaws.com/i/uajmhch8kz9iek5g0l10.png)

In the top right corner, click the **Settings** cog. Then click **Projects** on the left, and finally, **python_app**.

![2018-09-11-Stanley10.png](https://thepracticaldev.s3.amazonaws.com/i/9nm8siqv4s1zezca5q7n.png)

You will be on a path like this one: `circleci.com/gh/<username>/python_app`. Mine is `https://circleci.com/gh/NdagiStanley/python_app`. Click the **settings** cog next to the repo name: **python_app**.

![2018-09-11-Stanley11.png](https://thepracticaldev.s3.amazonaws.com/i/cmskp3k9ugp10rt75rjv.png)

It is important that you to become familiar with the settings that you can change for this project. I will touch on what is relevant to us now. 

In **Advanced Settings**, notice that **Only build pull requests** is turned off. This means that every push to GitHub will run on CircleCI, including PRs.

In **Chat Notifications**, notice that you can configure your Slack, HipChat, FlowDock, Campfire and IRC to be notified on every build. For Slack, [this][11] resource is handy.

In **[Status Badges](https://circleci.com/docs/1.0/status-badges/)**, notice the Markdown embed code. We will copy this code to paste into our README.

## ReadME - status badge

On our local machine, checkout to another Git branch by running:

```bash
git checkout -b add_readme
```

Open your editor and create a `README.md` file. Copy and paste the following lines into this file:

```
README.md
# PYTHON APPLICATION
This Python application repo was created to showcase the integration between GitHub and CircleCI.
[![CircleCI](https://circleci.com/gh/NdagiStanley/python_app.svg?style=svg)](https://circleci.com/gh/NdagiStanley/python_app)
```

I added a title and a brief description to mine.

Now, run the following commands:

```bash
git add .
git commit -m "Add README"
git push -u origin add_readme
``` 

If you go to https://github.com/<username>/python_app you will notice that we have a new branch: `add_readme`. We can go ahead and click <strong>Compare and pull request</strong>.

![2018-09-11-Stanley12.png](https://thepracticaldev.s3.amazonaws.com/i/wd4ab4pavrn86s1bms45.png)

## Opening a pull request

This is how I set up my PR:

![2018-09-11-Stanley13.png](https://thepracticaldev.s3.amazonaws.com/i/vgozvrujkiaro78dohf6.png)

Click **Create pull request** and in no time, this is what we get:

![2018-09-11-Stanley14.png](https://thepracticaldev.s3.amazonaws.com/i/j3ybpqysy55kja7vc7so.png)

A successful build! Now, click **Show all checks**. You will see that the check is from CircleCI.

![2018-09-11-Stanley15.png](https://thepracticaldev.s3.amazonaws.com/i/7jbfdi45kd2oe9wm9w9v.png)

Even the browser’s tab favicon shows a tick for the successful run: 

![2018-09-11-Stanley16.png](https://thepracticaldev.s3.amazonaws.com/i/qaa44wp3hqpe0p2bnii7.png)

If you click **Details**, this will redirect you to the build on CircleCI:

![2018-09-11-Stanley17.png](https://thepracticaldev.s3.amazonaws.com/i/5l8z4xacmt6pfivn8sr6.png)

Notice that the favicon here also shows that the build is successful:

![2018-09-11-Stanley18.png](https://thepracticaldev.s3.amazonaws.com/i/4759lygr9oto3q3yns7p.png)

At the top, click **python_app**

![2018-09-11-Stanley19.png](https://thepracticaldev.s3.amazonaws.com/i/f27khgbq24zjvkesa4qb.png)

You are redirected to the builds for this project:

![2018-09-11-Stanley20.png](https://thepracticaldev.s3.amazonaws.com/i/rz51hdmxetkpbbxp34fz.png)

## Conclusion

And there you have it! We have integrated GitHub with CircleCI. In summary, we set up a Python application and created tests for it. We then created a CircleCI config file and pushed the codebase to GitHub. Finally, we connected the GitHub repository we created to CircleCI.

If you followed through successfully, you can now set up your own project in GitHub and configure CI builds on CircleCI. The following links point to my references while writing this article.

[https://circleci.com/docs/2.0/configuration-reference/#full-example][12]
[http://flask.pocoo.org/][2]
[https://circleci.com/docs/2.0/configuration-reference/][13]

***

<i>About Stanley: From a young age, Stanley tinkered with electronics and building things with tech. Now, he’s an engineer at Andela and his work involves data, the web, and IoT. Stemming from his lifelong love of DIY, he’s on a personal journey of invoking the builder within and teaching others along the way. He cares about how technology affects society and seeks collaborations with others who are working to create positive impact.</i>

[1]: https://www.python.org/downloads/
[2]: http://flask.pocoo.org/
[3]: https://virtualenv.pypa.io/en/stable/ 
[4]: http://virtualenvwrapper.readthedocs.io/en/latest/ 
[5]: http://localhost:5000/
[6]: http://flask.pocoo.org/docs/1.0/testing/
[7]: https://damyanon.net/post/flask-series-testing/
[8]: https://circleci.com/docs/2.0/language-python/
[9]: https://github.com
[10]: https://circleci.com/
[11]: https://circleci.com/blog/slack-integration/
[12]: https://circleci.com/docs/2.0/configuration-reference/#full-example
[13]: https://circleci.com/docs/2.0/configuration-reference/
[14]: https://circleci.com/continuous-integration/
[15]: https://circleci.com/blog/setting-up-continuous-integration-with-github/