TutorialsLast Updated Oct 27, 202611 min read

Setting up continuous integration with GitHub and CircleCI

Stanley Ndagi

Fullstack Developer and Tech Author

Continuous integration (CI) 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 or the main branch. This allows small incremental updates that reach your users faster, in line with Agile software development methodology.

In this article, I will take you through the process of setting up a CI pipeline with GitHub and CircleCI. We will use a basic Python application to demonstrate the process, but you can follow along using your own personal project as well.

Here are the steps:

  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 your README with a badge
  7. Create a PR and see CircleCI in action

Prerequisites

To follow along with the tutorial, a few things are required:

  1. Python installed on your local system
  2. A CircleCI account
  3. A GitHub account

The complete code for this tutorial is in the CIRCLECI-GWP/python_app repository on GitHub.

Creating and building a simple Python app

For simplicity, you will create a Flask application. Flask is a micro-framework for Python. Don’t worry if you’ve never used Flask before — we’ll be building the basic hello world application found in the Flask documentation.

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

mkdir python_app && cd $_/

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

from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello_world():
    return "<p>Hello, World!</p>"

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 or, even better, virtualenvwrapper. We will use the module venv that comes as a part of Python3. Here is how:

  • Create the virtual environment:
python -m venv .venv

If the system has no python command (the python.org installer for macOS provides python3), use python3 instead.

You can use other names for your virtual environment, like in the next example.

python -m venv Env
  • Activate this environment:
source .venv/bin/activate

If you used another name for the environment, replace .venv with that name. You will notice the environment name just before the shell prompt, which tells 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:

deactivate

Running the app

Now it’s time to create a requirements.txt file in your editor. Add this content:

Flask
pytest

This file is used to specify the packages that your application depends on. You can install these packages using pip, which is the package manager for Python.

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

pip install -r requirements.txt

Note: If you deactivated your virtual environment prior to this step, you will first need to run source .venv/bin/activate.

The final command to run this application is:

flask --app hello run

The application is running on your browser at http://localhost:5000/.

Creating tests for your application

Software testing is an important skill for any developer, ensuring that your application works as intended and helping to catch bugs early. Writing tests can save you time and headaches down the line.

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

from hello import app

def test_home_route():
    with app.test_client() as c:
        response = c.get("/")
        assert response.data == b"<p>Hello, World!</p>"
        assert response.status_code == 200

This test verifies that your Flask application’s home route returns the correct HTML content and status code.

Learn more about testing Flask with Pytest.

Now you can run your test. Open Terminal and run:

python -m pytest

This command will execute the test file you just created. If everything is set up correctly, you should see output similar to this:

============================= test session starts ==============================
platform linux -- Python 3.15.1, pytest-9.1.1, pluggy-1.7.0
rootdir: /home/reader/python_app
collected 1 item

test_hello.py .                                                          [100%]

============================== 1 passed in 0.08s ===============================

This output indicates that the test passed successfully. The dot (.) represents a passing test, while an F would indicate a failure.

Creating a CircleCI config file

To automate your testing process, you’ll need to set up a CircleCI configuration file. This configuration will define how your tests are run and how your application is built and tested.

Create a .circleci folder and inside of that create a config.yml file. Then, copy these lines into it:

version: 2.1
orbs:
  python: circleci/python@4.0.0
jobs:
  build_and_test: # this can be any name you choose
    executor: python/default # use the default executor defined within the orb
    steps:
      - checkout # checkout source code
      - python/install-packages:
          pkg-manager: pip
          pip-dependency-file: requirements.txt
      - run:
          name: Run tests
          command: python -m pytest
workflows:
  build_test_deploy:
    jobs:
      - build_and_test

This file configures CircleCI to use the Python orb, which simplifies setting up the Python environment and running your tests. The build_and_test job checks out your source code, installs the necessary packages, and runs your tests using pytest. The workflows section defines a workflow called build_test_deploy that runs the build_and_test job.

Learn more about this config file.

Pushing to GitHub

Following DevOps best practices, you would typically initialize Git at the beginning of your project and make frequent, small commits. However, since this tutorial focuses on integrating CircleCI with GitHub, I intentionally delayed this step until now.

This is the current code structure:

.
├── .circleci
│   └── config.yml
├── hello.py
├── requirements.txt
└── test_hello.py

Open your editor and create a .gitignore file in the working directory. You will use this file to state the files and folders that you do not want to commit to Git. Copy these lines into that file:

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

# Environments
.env
.venv
env/
venv/
ENV/

Initialize Git and commit your code by running:

git init

git add .

git commit -m "initial commit"

If you do not already have a GitHub account, go to GitHub’s homepage and create one. If you are new to GitHub, you may want to read our tutorial on pushing a project to GitHub.

Next, create a repository by navigating to github.com/new.

Use the name python_app. Leave the rest of the default settings as-is and click Create repository.

The GitHub Create a new repository page with python_app entered as the repository name, Public visibility selected, and the Create repository button

After creating your new repository, you will be prompted about your repo.

The empty python_app repository on GitHub, showing Quick setup and the commands to push an existing repository from the command line

Run these commands to add the remote repository and push your code to GitHub. Replace <your-username> with the GitHub username that owns the repository:

git branch -M main
git remote add origin https://github.com/<your-username>/python_app.git
git push -u origin main

Configuring CircleCI

Now that the repo is on GitHub, you can finalize the CI pipeline by configuring CircleCI. Head on over to the CircleCI signup page. Click Sign up to create a CircleCI account. The GitHub connection comes later, when creating a project.

The CircleCI sign-up page with the Sign up button and the option to get started with the CircleCI CLI

Enter a work email and click Continue, then create a password.

The Create a CircleCI account form with a Work email field, a reCAPTCHA check, and the Continue button

You will get an email to verify your account. Click the link in the email to verify your account.

On the next screen, fill in a few onboarding questions by selecting options. I’ve gone with generic ones for now.

Click Let’s go to continue.

Next, start a new organization.

Enter the name of your organization. This is the name that will be used to identify your CircleCI account. Click Let’s go to continue.

The CircleCI organization name form, with python-app-tutorial entered in the Organization name field above the Let's go button

This will create a new organization for you on CircleCI. Next, you will be redirected to your organization’s Organization Home page. Go ahead and click Create a project.

The CircleCI Organization Home page for a new organization, with the Create a project card

Give the project a descriptive name, such as python_app, and click Next. CircleCI suggests build-and-test as the name of the first pipeline, and that name works for this tutorial.

Next, choose the repository. Under Connect your VCS provider and select your target repo, select GitHub Cloud.

The CircleCI Create a project page at the Pipeline step, with python_app as the project name, build-and-test as the pipeline name, and the GitHub Cloud, GitLab Cloud, GitLab Self-Managed, and Cursor Origin provider tiles

Connecting GitHub for the first time installs the CircleCI GitHub App. Select the GitHub account or organization that owns the python_app repository.

You can specify exactly which repositories CircleCI can access, or opt to give CircleCI access to all repositories in your GitHub organization. Choose All repositories or Only select repositories, then click Install & Authorize.

The GitHub Install & Authorize CircleCI App page, with All repositories selected, the permissions the app requests, and the Install & Authorize button

GitHub then returns to CircleCI. Select the python_app repository from the list.

Next, set up the trigger. Under Choose your starting trigger, CircleCI selects All pushes by default, so every push to the repository runs the pipeline.

The CircleCI Create your first pipeline step with the python_app repository selected and the starting trigger set to All pushes on the repository

The default trigger is all this tutorial needs, so keep it and click Next.

Because the repository already has a .circleci/config.yml file, CircleCI detects it and shows CircleCI config detected. Click Next, and the Review and finish page confirms Config detected. Then click Go to project.

The CircleCI Review and finish page, listing the python_app project, the build-and-test pipeline, the repository, the All pushes trigger, and the .circleci/config.yml workflow file on main

With that, your project on CircleCI is ready.

Once your project is created you will land on your pipelines page. CircleCI uses the specified .circleci/config.yml file to run your pipeline.

The pipeline runs on the next push to the repository. To start the first run now, click Trigger pipeline. Choose the main branch for both Config Source and Checkout Source, then click Run pipeline.

You can see the output on the pipelines page. Within no time, the build passes. Success!

The CircleCI pipelines page for python_app, showing the first build-and-test pipeline on the main branch with a Success status for the build_test_deploy workflow

Now that your project is set up, it’s worth getting familiar with the optional settings available to you. Let’s look at a relevant example.

For this project, click Project, select Project settings, and then click Project Setup on the left.

The build-and-test pipeline has one trigger, All pushes. This means that every push to GitHub will run on CircleCI, including PRs. To build less often, expand the trigger, click Edit trigger, and choose a different event, such as PR opened or pushed to, default branch and tag pushes. Sometimes, in a large team setting, this setting can help moderate use of build minutes.

The CircleCI Project Setup page with the trigger Event list open, showing options such as All pushes, Pushes to default branch, and PR opened or pushed to, default branch and tag pushes

CircleCI setup without config.yml

If a repository doesn’t have a .circleci/config.yml file yet, CircleCI provides a prompt to paste into an AI coding agent. The agent generates a config file and commits it to a new branch in the repository. For a project that already uses GitHub Actions, select Use existing GitHub Actions workflow file instead. This tutorial uses the config file created earlier.

Adding a CI status badge to GitHub

A status badge is a great way to show the build status of your project right on your GitHub repository. It provides a visual indicator of whether your latest build passed or failed, which is helpful for both you and your collaborators.

On your local machine, check out to another Git branch by running:

git checkout -b add_readme

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

# PYTHON APPLICATION

This Python application repo was created to showcase the integration between GitHub and CircleCI.
[![CircleCI](https://dl.circleci.com/status-badge/img/circleci/<org-id>/<project-id>/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/circleci/<org-id>/<project-id>/tree/main)

This adds a title, a description and a status badge.

Replace the last line with the project’s own badge code. In CircleCI, click Project, select Project settings, and then click Status Badges. The Branch is main and the Format is Markdown by default, so click Copy. For a private repository, click Add API token on that page first so the badge can load.

The CircleCI Status Badges settings page for python_app, with the main branch, the Markdown format, and the Copy button next to the embed code

Now, run these commands:

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

Your https://github.com/<your-username>/python_app repo has a new branch: add_readme. Click Compare & pull request.

The python_app repository on GitHub with a banner saying add_readme had recent pushes and a Compare & pull request button

Triggering a build via a pull request

After adding the status badge, the next step is to create a pull request (PR) to merge your changes into the main branch. This will allow us to trigger a build and ensure everything is set up correctly.

Here is how I set up my PR. The PR’s title is autogenerated as the commit message. This is optional.

#### What does this PR do?

Adds README.md file and a CircleCI badge in it.

Click Create pull request and in no time, you have a successful build!

The Add README pull request on GitHub, showing All checks have passed with the ci/circleci: build_and_test check expanded

Note that I clicked on the chevron arrow down icon to reveal the successful check is from CircleCI. Even the browser’s tab favicon shows a green tick for the successful run.

If you click Details next to ci/circleci: build_and_test, this will redirect you to the build on CircleCI:

The CircleCI job page for the Add README push on the add_readme branch, with the build_and_test steps shown passing

Note that the favicon here is green, showing that the build is successful.

Go ahead and merge the PR. You can also delete the branch if you want to.

This will trigger the pipeline to run again, but this time on the main branch. You can see this in the CircleCI dashboard.

The CircleCI pipelines page for python_app, showing three successful pipelines: the merge to main, the add_readme branch, and the first run on main

Conclusion

There you have it! You have integrated GitHub with CircleCI.

In summary, you set up a Python application and created tests for it. You then created a CircleCI config file and pushed the codebase to GitHub. Finally, you connected the GitHub repository you created to CircleCI.

By adding continuous integration to your workflow, you benefit from automated testing, ensuring that your code is always in a deployable state. This helps catch bugs early, improves code quality, and allows for faster, more reliable updates.

If you followed through successfully, you can now set up your own project in GitHub and configure CI builds on CircleCI. As a next step, consider adding automated deployments for your Flask application to complete your CI/CD pipeline and fully automate your development workflow. If your team also uses GitHub Actions, you can trigger CircleCI pipelines directly from a GitHub Actions workflow to combine both platforms.