Why a Raspberry Pi 4 for GitLab CI?
If you already host a GitLab instance on a NAS or a tiny server, a Pi 4 can be the perfect “just‑add‑a‑little‑more‑power” solution.
It’s cheap, low‑power, and its 4‑core Cortex‑A72 at 1.5 GHz does more than you’d expect for unit tests, linting, and even modest Docker builds—just keep the job size in check.
Prerequisites
| Item | What you need |
|---|---|
| Raspberry Pi 4 | 2 GB or 4 GB RAM works; 8 GB gives headroom for Docker. |
| Micro‑SD card | 32 GB+, Class 10. |
| Power supply | Official 5 V/3 A USB‑C. |
| Network | Wired Ethernet is best for stability. |
| Host OS | Raspbian Bookworm (Debian 12) or Ubuntu 22.04 LTS for ARM. |
| GitLab instance | Self‑hosted or GitLab.com, with an API token for runners. |
If you’re new to the Pi, flash the OS first and make sure you can SSH in.
For a fresh Raspbian image, enable SSH by placing an empty ssh file in the boot partition or run raspi-config after boot.
Step 1 – Prepare the Pi
# Update everything
sudo apt update && sudo apt upgrade -y
# Basic tooling
sudo apt install -y curl ca-certificates git
# Optional: Docker if you want Docker‑based runners
sudo apt install -y docker.io
sudo usermod -aG docker $USER
newgrp docker
Docker is optional; the native GitLab runner can run jobs in a container or directly on the host.
If you go the Docker route, remember the Pi’s limited RAM—keep container memory limits low.
Step 2 – Install the GitLab Runner binary
The official runner ships as a pre‑compiled binary for ARMv7 and ARM64.
Grab the latest release from GitHub: https://github.com/gitlabhq/gitlab-runner/releases
RUNNER_VERSION=$(curl -s https://gitlab.com/api/v4/projects/2789645/releases | jq -r '.[0].tag_name')
curl -L https://gitlab-runner-downloads.s3.amazonaws.com/${RUNNER_VERSION}/binaries/gitlab-runner-linux-arm64 -o /usr/local/bin/gitlab-runner
chmod +x /usr/local/bin/gitlab-runner
Tip:
jqis handy for parsing JSON, but you can hard‑code the version if you prefer.
Step 3 – Register the Runner
sudo gitlab-runner register
You’ll be prompted for:
- GitLab instance URL – e.g.
https://gitlab.example.com/ - Registration token – under Admin Area → Runners or Project → Settings → CI/CD → Runners.
- Description –
Pi4-CI-Runner - Tags – e.g.
pi4,arm,small - Executor –
shellfor native jobs ordockerif you installed Docker.
If you pick docker, you’ll need a default image, e.g.:
docker image: debian:bookworm
After registration, the runner appears in the GitLab UI.
A quick test is to push a simple .gitlab-ci.yml that runs echo hello.
Step 4 – Configure the Runner as a Service
Running the runner as a systemd service keeps it alive across reboots and lets you manage it with ease.
sudo gitlab-runner install --user gitlab-runner --working-directory /home/gitlab-runner
sudo systemctl enable gitlab-runner
sudo systemctl start gitlab-runner
Check the status:
sudo systemctl status gitlab-runner
You should see active (running).
Step 5 – Optimize for the Pi
5.1 Limit CPU and Memory
By default the runner will use all cores.
If you run multiple jobs, the Pi can throttle.
Edit /etc/gitlab-runner/config.toml and add:
[[runners]]
name = "Pi4-CI-Runner"
executor = "shell"
limit = 2 # Max 2 concurrent jobs
[runners.custom_build_dir]
dir = "/tmp/build"
For Docker executors, set resource limits per job in .gitlab-ci.yml:
job:
image: debian:bookworm
script:
- make test
tags:
- pi4
services:
- name: redis:alpine
command: ["--maxmemory", "256mb"]
5.2 Reduce Disk Wear
The SD card can wear out if the runner writes a lot of logs.
Mount a small tmpfs for build artifacts:
sudo mkdir /tmp/build
sudo mount -t tmpfs -o size=512m tmpfs /tmp/build
Add this to /etc/fstab so it stays mounted after reboot:
tmpfs /tmp/build tmpfs defaults,size=512m 0 0
5.3 Keep the System Secure
-
Firewall:
ufwis pre‑installed. Allow only SSH and the ports you need.sudo ufw allow ssh sudo ufw enable -
SSH hardening: Disable password auth, use key‑based login, and change the default port if you’re on a public network.
-
Runner token rotation: If the token is compromised, revoke it in GitLab and re‑register.
Step 6 – Sample .gitlab-ci.yml for a Small Project
stages:
- lint
- test
- build
variables:
CACHE_DIR: "$CI_PROJECT_DIR/.cache"
cache:
paths:
- .cache/
lint:
stage: lint
script:
- pip install flake8
- flake8 src/
tags:
- pi4
only:
- merge_requests
test:
stage: test
script:
- pip install -r requirements.txt
- pytest tests/
tags:
- pi4
artifacts:
paths:
- reports/
expire_in: 1 week
build:
stage: build
script:
- docker build -t myapp:${CI_COMMIT_SHA} .
tags:
- pi4
only:
- main
This file shows:
- Using tags to target the Pi runner.
- Caching dependencies to speed up jobs.
- Artifacts that survive a week—useful for debugging.
Common Pitfalls & Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
| Runner never shows up in GitLab | Token mismatch or network issue | Verify the token, check curl https://gitlab.example.com/ from the Pi |
| Jobs fail with “Out of memory” | Docker image too large or job uses too much RAM | Add mem_limit in .gitlab-ci.yml or switch to a lighter image |
| Slow job start | SD card I/O bottleneck | Use a high‑speed SD card or an external SSD via USB‑3 |
| Runner stops after reboot | Service not enabled | sudo systemctl enable gitlab-runner |
| SSH key not accepted | Wrong permissions on ~/.ssh |
chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys |
Scaling Beyond One Pi
If you need more concurrency:
- Multiple Pi 4s: Register each with unique tags and let GitLab distribute jobs automatically.
- Kubernetes on a Pi: Projects like k3s can run lightweight clusters, but the overhead may outweigh the benefit for simple CI.
- Hybrid approach: Use the Pi for quick jobs and a more powerful server for heavy builds.
Final Thoughts
A Raspberry Pi 4 can be a surprisingly capable CI runner for small‑to‑medium projects.
Its low power draw and minimal cost make it ideal for a homelab or a personal dev environment.
Keep the runner lightweight, limit resources, and harden the system, and you’ll run reliable CI pipelines without breaking the bank.