Raspberry Pi CI/CD Server

Introduction

Woodpecker CI is a lightweight CI/CD platform built for simplicity and resource efficiency. Unlike Jenkins (heavy) or Drone (slower ARM support), Woodpecker uses only ~200MB RAM and has native ARM builds. This guide walks you through deploying a self-hosted CI/CD server on your Pi.

Prerequisites

• Raspberry Pi 4 or 5 (4GB+ RAM recommended)
• Docker and Docker Compose installed
• Git repository on GitHub or Gitea
• Basic SSH access to your Pi

Step 1 — Install Docker and Docker Compose

Update your system and install Docker:

sudo apt update && sudo apt upgrade -y
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

Verify Docker works:

docker --version
docker compose version

Step 2 — Create Woodpecker docker-compose.yml

Create a directory for Woodpecker and add this compose file:

mkdir -p ~/woodpecker
cd ~/woodpecker

docker-compose.yml:

version: '3.8'

services:
  server:
    image: woodpeckerci/woodpecker-server:latest-alpine
    container_name: woodpecker-server
    ports:
      - "8000:8000"
    volumes:
      - ./data:/var/lib/woodpecker
    environment:
      WOODPECKER_HOST: https://your-pi-hostname.local:8000
      WOODPECKER_GITHUB: "true"
      WOODPECKER_GITHUB_CLIENT: "YOUR_GITHUB_CLIENT_ID"
      WOODPECKER_GITHUB_SECRET: "YOUR_GITHUB_SECRET"
      WOODPECKER_ADMIN: "your-github-username"
      WOODPECKER_AGENT_SECRET: "super-secret-agent-key"
    restart: always

  agent:
    image: woodpeckerci/woodpecker-agent:latest-alpine
    container_name: woodpecker-agent
    depends_on:
      - server
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      WOODPECKER_SERVER: http://server:9000
      WOODPECKER_AGENT_SECRET: "super-secret-agent-key"
    restart: always

Replace YOUR_GITHUB_CLIENT_ID, YOUR_GITHUB_SECRET, and your-github-username with your values. Get OAuth credentials from GitHub: Settings → Developer settings → OAuth Apps.

Step 3 — Start Woodpecker

docker compose up -d

Check logs:

docker compose logs -f server

Access the server at http://localhost:8000 (or your Pi's IP). Log in with GitHub.

Step 4 — Add Webhooks and Connect Repository

1. Activate your repository in Woodpecker's UI
2. Woodpecker automatically creates a GitHub webhook
3. Push to test the webhook connection

Step 5 — Write Your First Pipeline

Create .woodpecker.yml in your repository root:

steps:
  build:
    image: golang:1.21-alpine
    commands:
      - go build -o app .

  test:
    image: golang:1.21-alpine
    commands:
      - go test ./...

  deploy:
    image: alpine:latest
    commands:
      - echo "Deploying to production..."
    when:
      branch: main
      event: push

Push this file; Woodpecker triggers automatically on the next push.

Resource Usage and Performance

Woodpecker on Pi uses approximately:

• Server: 150-200MB RAM
• Agent: 100-150MB RAM per concurrent build
• CPU: ~15% during builds (Pi 4)

With 4GB RAM, you can comfortably run 1-2 concurrent builds. Use docker stats to monitor:

docker stats woodpecker-server woodpecker-agent

Troubleshooting

Agent won't connect: Verify WOODPECKER_AGENT_SECRET matches in both server and agent. Check logs: docker compose logs agent

Webhook not triggering: Confirm the repository is activated in Woodpecker. Check repository settings in GitHub to see webhook delivery status.

Out of memory: Reduce concurrent builds or limit agent container memory: docker run --memory=512m

Slow builds on Pi: Use golang:alpine or other lightweight images. Cache dependencies between runs with Woodpecker volumes.

Woodpecker turns a Pi into a functional CI/CD server without the overhead of traditional Jenkins deployments. Pair this with Gitea for a fully self-hosted Git workflow, or integrate directly with GitHub for hybrid infrastructure.

Summary

You now have a self-hosted CI/CD server running on your Raspberry Pi. Woodpecker CI handles automated builds and deploys with minimal resource overhead — perfect for homelab projects and personal repos.