Gitlab runner on Raspberry Pi
Tags: git, raspberrypi, tutorial, docker
Published: 2022-03-23 12:01:09

There are many reasons why to run Gitlab runner on your own machine. And here is the tutorial how to do it with Raspberry Pi. Including installation of Docker, which is most likely needed.

---

> 🇨🇿 V češtině si lze článek přečíst na [kutac.cz](https://www.kutac.cz/pocitace-a-internety/gitlab-runner-na-raspberrypi) 

The first step is to install Raspberry Pi OS to SD card. That is actually super easy. Just download and run **Raspberry Pi Imager** from [raspberrypi.com/software](https://www.raspberrypi.com/software/). Select recommended version, target SD card, and start writing process. Then insert the SD card into Raspberry Pi and plug power. After Raspberry Pi OS will start, it suggests you to change password, connect to WiFi and install updates. I highly recommend to do all of that.


![Raspberry Pi OS installation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8bdaae1yzmk5qatzooz3.png)

## Install Docker and git

Docker will be most likely needed, while git is required. Luckily, git should be already preinstalled. Just try to run `git --version` to confirm that. The preferred way of installing Docker is via `apt`, however, that is not supported for Raspberry Pi. It is required to use [the Convenience script](https://docs.docker.com/engine/install/debian/#install-using-the-convenience-script). You can download and execute it with the command below. Because Docker requires `root` access, it is suggested to add the current user into the [docker group](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). Also included in the script below.

```bash
# Downloads script and start installation
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Adds current user to docker group
sudo groupadd docker # Most likely returns an error, that group already exists
sudo usermod -aG docker ${USER}
groups ${USER} # List all groups, current user belongs to
```

![Installing Docker](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/g0b2iovnab2piyb2hd0c.png)

After restarting, it is possible to test if Docker is running. Just execute `docker run hello-world`. It should print out some basic information.

## Install Gitlab runner

Gitlab runner can be installed via script similarly to Docker. However, it ends up with an error, that the current distribution is not supported. Raspberry Pi OS is based on Debian but has its own ID. So it is required to print out the current OS version and pass some values into the script.

```bash
# Prints out current OS version
cat /etc/os-release
# Change os and dist variable with values from output above
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo os=debian dist=bullseye bash
# Now you can install Gitlab runner
sudo apt install gitlab-runner
```

![Add Gitlab APT repository and install Gitlab runner](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/in39oykc3g4lrfnojchz.png)

## Register Gitlab runner

The last step is to register Gitlab runner. One installation can handle multiple projects or project groups. The first step is to copy the registration token in CI/CD settings of project or group. It might be worth disabling shared runners too.

![Gitlab CI/CD settings](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cfck4jjvdxw9qde5spp4.png)

To start the registration process execute `sudo gitlab-runner register` command. It asks for multiple parameters and you should enter docker for executor parameter.


![Register Gitlab runner](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tdd6m84pqd10fvil07p9.png)

## Issues with custom Docker image

If you are using in pipeline custom Docker image, you might be facing issues with incompatibility. Your computer is most likely amd64 architecture, while Raspberry is arm architecture. So your docker image will not work on Raspberry. You have to build docker image on Raspberry directly or use `buildx` extension. I did this for my [Docker FTP Deployer](https://gitlab.com/pavel.kutac/docker-ftp-deployer/-/commit/5f0b84152600ec35d992b070aa298c555025fd18) repository. You can find more about Docker FTP Deployer in my article [Parallel incremental FTP deploy in CI pipeline](https://dev.to/arxeiss/parallel-incremental-ftp-deploy-in-ci-pipeline-2511).