Running GITLAB tests locally with Docker CE

The possibility to test integration on our projects when using Gitlab gives us a powerful testing tool to be sure that the code we submit to the repository will work as intended and wont break anything. The way that Gitlab does Continuous Integration (CI) tests is by using Docker containers that can be deployed at demand to test specific aspects of our project.

A problem encountered during development is that sometimes you would prefer testing your code locally before pushing it to the repository. It could sometimes be a challenge to get all the moving parts of a project running together on your system. Luckily Gitlab offers the possibility to install their GitLab Runner, responsible for executing the CI tests on your machine. Combining the GitLab Runner with docker, we can very easily run the needed docker container with a predefined image, deploy our code to the container and test everything locally without errors introduced to the repository.

This blog focuses on installing the GitLab Runner on a Linux system, but there is also the possibility to install and use it on Windows and MACOS machines.

Installing Docker CE

Before we install and configure the GitLab Runner, we need to be sure we have docker running on our machine.

1. If you already have docker installed you can check if new version is available. It is not a problem using earlier version of Docker CE, but it is recommended to updating to the latest version. First we uninstall the old version of Docker CE:

$ sudo apt-get remove docker docker-engine docker.io containerd runc

2. Configure apt to be able to use repositories over HTTPS. This can be done by installing the following packages:

$ sudo apt-get install 
    apt-transport-https 
    ca-certificates 
    curl 
    gnupg-agent 
    software-properties-common

3. Add Docker's official GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

You can verify that the correct key was added by comparing the fingerprint

$ sudo apt-key fingerprint <docker_ce_gpg_fingerprint>

4. Set up the repository to use (we are using the stable release)

sudo add-apt-repository 
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu 
   $(lsb_release -cs) 
   stable"

5. Install Docker CE

First we update the apt package index

$ sudo apt-get update

Once the package index has been updated we can install the docker distribution.

sudo apt-get install docker-ce docker-ce-cli containerd.io

6. You can test if Docker CE was installed correctly by running the "hello-world" example

$ sudo docker run hello-world

Installing the Gitlab CI Runner

Once the Docker CE has been installed and running correctly we can install the GitLab Runner and test our code.

1. Add the Gitlab's official repository

$ curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash

2. Install the latest version of GitLab Runner

$ sudo apt-get install gitlab-runner

it is possible to install a specific version of the Gitlab Runner by specifying the version at the end of the command by adding "=X.X.X" where the "X.X.X" is the version to be installed.

1. It is also possible to register the runner to be recognized by the Gitlab repository as a valid runner.

Running the Gitlab Runner

To run and test our code we need first to create a "gitlab-ci.yml" file at the root of our project. In this file we will define the stages in the testing, any variables, scripts and commands to be run during the different stages.

stages:
 - test

test:pylint:
  stage: test
  image: python:2.7
  script:
      - pip install pylint --quiet
      - pylint --ignored-classes=_socketobject *.py

In the example above we define a stage called "test" that will use a python:2.7 docker image to run pylint and test the style of our python code.

To run the test locally we will use the "gitlab-runner exec" command by specifying how the test will be executed and which test (if multiple are defined in the gitlab-ci.yml file) should be run.

$ gitlab-runner exec docker test:pylint

The command will run a docker python:2.7 image, clone your project from gitlab to the container, install the dependencies and execute the test.

This blog post is licensed under CC BY-SA 4.0