What is GitLab Runner

GitLab Runner is an agent that runs GitLab CI/CD (Continues Integration/Continuous Deployment) jobs in a pipeline. It's heavily utilized in the world of DevOps to provision and configure infrastructure. The GitLab Runner can be installed as a binary on Linux, MacOS or Windows. It can also be installed as a container.

On this tutorial, I will walk through installing and configuring GitLab Runner as a container using a Docker image on a RPI-4..yaay. I will make it very swift to get you started and won't feel a thing. I will not bore you with details, but if there are useful links for further study, I will definitely throw it in. The goal is to get you started with GitLab Runners and the rest is on you.

As a bonus, we will run our first job of building docker images and push them to Docker hub. Enough reading, let's get our hands dirty, I mean our keyboards 😉

To lean more about GitLab Runners, refer to GitLab official documentation.

Note: Sensitive information will be pixilated or erased. This should not alter the quality of the tutorial.

Run a GitLab Runner Container on a RPI-4

If you don't have Docker installed on your RPI-4, you may refer to my Docker on Ubuntu 20.04 Raspberry Pi 4 tutorial.

1- Let's create a persistent Docker volume for the runner. On your RPI-4 terminal, run the following command:

docker volume create gitlab-runner-volume

Note: you can change the volume name gitlab-runner-volume to any name of your chosen, but you should be consistent as we will use the volume name to bind the container to the RPI-4 local host.

2- Run the below commands to start GitLab Runner container:

docker run -d --name gitlab-runner --restart always --env TZ=US \
   -v  gitlab-runner-volume:/etc/gitlab-runner \
   -v /var/run/docker.sock:/var/run/docker.sock \
   gitlab/gitlab-runner:alpine

The only parameters you have the options to change are:

• the name flag, gitlab-runner
• the volume name, gitlab-runner-volume
• the gitlab runner image, gitlab/gitlab-runner:alpine
• the env flag, TZ=US

For more information about the installation process, here is the link GitLab's official documentation.

3- Capture the GitLab Runner token:

We do need to head to our GitLab account and grab the runner's token. If you don't have a GitLab account, you can create one for free. Here is the link.

Now, we need to create a repository to host our project. From GitLab, let's click on create New project. On the Create new project, select create blank project. Then, give the project a name and click Create project. In my case, I named my repo, GitLab-Runner-RPI-4.

From the repository, let's click on settings, CI/CD and then Expand on the Runners section as shown below.

• Capture the token and save it on a note pad. We will need the token for the next step.
• Disable Enable shared runners for this project.

4- Register the GitLab Runner:

Replace the token place holder after registration-token with the one from our note pad, and then run the following commands on your RPI-4 terminal:

docker run --rm -it -v gitlab-runner-volume:/etc/gitlab-runner gitlab/gitlab-runner:alpine register -n \
  --url https://gitlab.com/ \
  --registration-token GR1348941EDhyNWqfxPttukrGVKJd \
  --executor docker \
  --description "My Docker Runner" \
  --docker-image "docker:20.10.12-dind-alpine3.15" \
  --docker-privileged \
  --docker-volumes "/certs/client"

If everything went smooth, you should not exhibit no errors as shown below.

To confirm that the GitLab Runner container is running, run the below Docker command:

docker ps -a

Alright, this is a great indication that we have successfully configured GitLab Runner on RPI-4. Now, we are ready to make some actions 💥

Build and Push Docker images to Docker Hub using GitLab Runner on GitLab

1- First of all, we need get a token from our Docker hub account to avoid using account password. The token is to allow GitLab Runner to authenticate and push Docker images to our Docker hub repository. If you don't know what Docker hub is, it is the world's largest library for container images.

On Docker hub account settings, click on Security, New Access Token and generate a Read, Write, Delete token. Docker hub free account allows for one active token. Capture the token and save to a note pad.

2- From GitLab repo, which have we have created previously:

• Click on Clone and copy the Clone with HTTPS link.
• On your RPI-4 terminal and in a folder of your chosen, run the below command. This is where the repo will be saved locally:

git clone `your-Clone-with-HTTPS-link`

Note: the git clone command will prompt you to enter your GitLab credentials for authentication.

3- cd into the repo and either use a text editor or the terminal to edit the .gitlab-ci.yml file. The file should only contain the following code. Be very careful with the indentation. Lastly, save the file:

image: docker:19.03.12

variables:
    IMAGE_NAME: "test:1.0.0"
    DOCKER_TLS_CERTDIR: "/certs"

services:
    - docker:19.03.12-dind
before_script:
  - docker info
build image:
    stage: build 
    script:    
        - docker build -t $REGISTRY_USER/$IMAGE_NAME .
        - docker login -u $REGISTRY_USER -p $DOCKER_HUB_TOKEN
        - docker push $REGISTRY_USER/$IMAGE_NAME

4- We will create a simple Dockerfile. The runner will use this Dockerfile to build a Docker image and push it to Docker hub. For right now, we will keep the Dockerfile VERY simple. Once the image is built from the Dockerfile, it will echo Hello World.
With your preferred text editor or terminal, create and name a file Dockerfile without any extension. Then save it in the same local repo.

FROM alpine
RUN echo "Hello World"

Note: In the local repo, we should have two files, Dockerfile and .gitlab-ci.yml. A README file might be there as well.

5- We will need to head back to GitLab repo to create two variables. On Settings, click on CI/CD, then expand Variables. We will click on Add variable to create two variables:

• Key: REGISTRY_USER
  Value: your Docker hub username NOT the email

• Key: DOCKER_HUB_TOKEN
  Value: the token which we generated from Docker hub

Note: the flags should be unchecked for simplicity for the two variables.

6- Now, we push the local repo to GitLab repo (remote repo) to start the GitLab Runner pipeline process. Yes, once the remote repo is updated, the runner will be triggered. Let's get back to our terminal on the RPI-4 and from within the local repo, run the following git commands:

git add -A
git commit -am "first test"
git push

If you head back to our GitLab repo and click on CI/CD under Pipelines, you would notice that the pipeline is running.

Moreover, if you click on the running status and you would be directed to the current stage, which is Build.

Here, click on build image, you shall see more details about the current build status. The goal is to see Job succeeded.

Once you see Job succeeded and passed status in green, you can start doing your victory dance 👯 👯

If we head back to Docker hub account, we should see that our Docker image test:1.0.0 has been successfully pushed to the repo.

Conclusion:

By the end of this tutorial, we have successfully configured a GitLab Runner on a RPI-4, created a GitLab repo and registered GitLab Runner to it. Finally, we created a Hello World Docker image from a Dockerfile and had the runner building the Docker image and pushing it to our Docker hub account.
Now, off you go and the sky is the limit.