DEV Community

Cover image for Gitlab runner on Raspberry Pi
Pavel Kutáč
Pavel Kutáč

Posted on

Gitlab runner on Raspberry Pi

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

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. 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

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. 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. Also included in the script below.



# 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


Enter fullscreen mode Exit fullscreen mode

Installing Docker

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.



# 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


Enter fullscreen mode Exit fullscreen mode

Add Gitlab APT repository and install Gitlab runner

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

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

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 repository. You can find more about Docker FTP Deployer in my article Parallel incremental FTP deploy in CI pipeline.

Top comments (0)