Running a Self‑Hosted GitLab CI Runner on a Raspberry Pi 4

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: jq is 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:

  1. GitLab instance URL – e.g. https://gitlab.example.com/
  2. Registration token – under Admin Area → Runners or Project → Settings → CI/CD → Runners.
  3. Description – Pi4-CI-Runner
  4. Tags – e.g. pi4,arm,small
  5. Executor – shell for native jobs or docker if 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: ufw is 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.

See also