Setup Gitea Runner

Pengenalan

Gitea Runner adalah komponen eksekutor yang menjalankan workflow jobs dari Gitea Actions. Runner ini kompatibel dengan GitHub Actions dan dapat dijalankan dalam berbagai mode eksekusi.

Prerequisites

Sebelum menginstall Gitea Runner, pastikan:

• Gitea Server sudah terinstall dan berjalan (versi 1.19+)
• Docker terinstall (untuk Docker executor)
• Kubernetes cluster tersedia (untuk Kubernetes executor)
• Akses network ke Gitea Server
• User dengan permission untuk register runner

Metode Instalasi

1. Binary Installation (Linux)

Download Binary

# Download latest release
wget https://dl.gitea.com/act_runner/latest/act_runner-linux-amd64

# Rename dan beri permission execute
mv act_runner-linux-amd64 act_runner
chmod +x act_runner

# Move ke system path
sudo mv act_runner /usr/local/bin/

Verifikasi Instalasi

act_runner --version

2. Docker Installation

Pull Image

docker pull gitea/act_runner:latest

Run dengan Docker

docker run -d \
  --name gitea-runner \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/config:/config \
  gitea/act_runner:latest

3. Kubernetes Installation

Menggunakan Deployment

Buat file gitea-runner-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gitea-runner
  namespace: gitea
spec:
  replicas: 3
  selector:
    matchLabels:
      app: gitea-runner
  template:
    metadata:
      labels:
        app: gitea-runner
    spec:
      containers:
      - name: runner
        image: gitea/act_runner:latest
        env:
        - name: GITEA_INSTANCE_URL
          value: "https://gitea.example.com"
        - name: GITEA_RUNNER_REGISTRATION_TOKEN
          valueFrom:
            secretKeyRef:
              name: gitea-runner-secret
              key: token
        volumeMounts:
        - name: runner-data
          mountPath: /data
        - name: docker-sock
          mountPath: /var/run/docker.sock
      volumes:
      - name: runner-data
        emptyDir: {}
      - name: docker-sock
        hostPath:
          path: /var/run/docker.sock
          type: Socket

Apply deployment:

kubectl apply -f gitea-runner-deployment.yaml

Registrasi Runner

1. Generate Registration Token

Dari Gitea Web UI:

1. Login sebagai administrator
2. Navigasi ke Site Administration → Actions → Runners
3. Click Create new Runner
4. Copy Registration Token

Atau via API:

curl -X POST "https://gitea.example.com/api/v1/admin/runners/registration-token" \
  -H "Authorization: token YOUR_GITEA_TOKEN" \
  -H "Content-Type: application/json"

2. Register Runner

Method 1: Interactive Registration

act_runner register

Akan muncul prompt:

? Gitea instance URL: https://gitea.example.com
? Runner token: [paste your registration token]
? Runner name: my-runner-01
? Runner labels: ubuntu-latest,docker

Method 2: Non-Interactive Registration

act_runner register \
  --instance https://gitea.example.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name runner-01 \
  --labels ubuntu-latest:docker://node:20

3. Verifikasi Registrasi

Cek di Gitea UI:

• Site Administration → Actions → Runners
• Runner status harus "Idle" atau "Active"

Konfigurasi Runner

File Konfigurasi

Setelah registrasi, file config dibuat di .runner atau lokasi yang ditentukan.

Edit config.yaml:

# Log level
log:
  level: info

# Runner settings
runner:
  # Nama runner
  name: runner-01
  
  # Jumlah worker concurrent
  capacity: 3
  
  # Timeout untuk job (dalam detik)
  timeout: 3600
  
  # Labels yang di-support
  labels:
    - "ubuntu-latest:docker://node:20-bullseye"
    - "ubuntu-22.04:docker://catthehacker/ubuntu:act-22.04"
    - "alpine:docker://node:20-alpine"

# Cache settings
cache:
  enabled: true
  dir: "/tmp/cache"
  
  # Cache size limit (dalam MB)
  max_size: 5000

# Container settings
container:
  # Network untuk containers
  network: "bridge"
  
  # Enable privileged mode
  privileged: false
  
  # Container options
  options: "-v /data:/data"

# Host settings
host:
  # Working directory
  workdir_parent: "/tmp/actions"

Executor Types

1. Docker Executor

Paling umum digunakan, menjalankan jobs dalam Docker container.

Keuntungan:

• Isolated environment
• Consistent builds
• Support official actions

Konfigurasi:

runner:
  labels:
    - "ubuntu-latest:docker://catthehacker/ubuntu:act-latest"
    - "node-20:docker://node:20-bullseye"

2. Shell Executor

Menjalankan job langsung di host machine.

Keuntungan:

• Faster execution (no container overhead)
• Direct access ke host resources

Konfigurasi:

runner:
  labels:
    - "linux:host"
    - "self-hosted:host"

Warning: ⚠️ Shell executor kurang secure karena langsung akses host

3. Kubernetes Executor

Menjalankan job sebagai Kubernetes pods.

Keuntungan:

• Scalable
• Resource management
• Cloud-native

Konfigurasi:

runner:
  labels:
    - "kubernetes:kubernetes://node:20"
    
kubernetes:
  namespace: "gitea-runners"
  pod_template: "/config/pod-template.yaml"

Menjalankan Runner

Foreground (untuk testing)

act_runner daemon

Background dengan systemd

Buat service file /etc/systemd/system/gitea-runner.service:

[Unit]
Description=Gitea Actions Runner
After=network.target

[Service]
Type=simple
User=gitea-runner
WorkingDirectory=/var/lib/gitea-runner
ExecStart=/usr/local/bin/act_runner daemon --config /etc/gitea-runner/config.yaml
Restart=always
RestartSec=10

# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/gitea-runner

[Install]
WantedBy=multi-user.target

Enable dan start service:

sudo systemctl daemon-reload
sudo systemctl enable gitea-runner
sudo systemctl start gitea-runner
sudo systemctl status gitea-runner

Logs

Lihat logs runner:

# Systemd logs
sudo journalctl -u gitea-runner -f

# Docker logs
docker logs -f gitea-runner

# File logs
tail -f /var/lib/gitea-runner/logs/runner.log

Multiple Runners

Scaling Runners

Untuk meningkatkan capacity, jalankan multiple runners:

Method 1: Multiple Instances

# Runner 1
act_runner daemon --config /etc/runner1/config.yaml

# Runner 2
act_runner daemon --config /etc/runner2/config.yaml

# Runner 3
act_runner daemon --config /etc/runner3/config.yaml

Method 2: Docker Compose

version: '3'

services:
  runner-1:
    image: gitea/act_runner:latest
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./runner1:/config
      
  runner-2:
    image: gitea/act_runner:latest
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./runner2:/config
      
  runner-3:
    image: gitea/act_runner:latest
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./runner3:/config

Method 3: Kubernetes ReplicaSet

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gitea-runner
spec:
  replicas: 5  # Scale ke 5 runners
  selector:
    matchLabels:
      app: gitea-runner
  template:
    metadata:
      labels:
        app: gitea-runner
    spec:
      # ... pod spec

Labels Strategy

Labels menentukan dimana job akan berjalan.

Standard Labels

runner:
  labels:
    # OS-based labels
    - "ubuntu-latest:docker://catthehacker/ubuntu:act-latest"
    - "ubuntu-22.04:docker://catthehacker/ubuntu:act-22.04"
    - "ubuntu-20.04:docker://catthehacker/ubuntu:act-20.04"
    
    # Language-specific labels
    - "node-20:docker://node:20-bullseye"
    - "python-3.11:docker://python:3.11-slim"
    - "golang-1.21:docker://golang:1.21-alpine"

Custom Labels

runner:
  labels:
    # Environment labels
    - "production:docker://alpine:latest"
    - "staging:docker://alpine:latest"
    
    # Purpose labels
    - "build:docker://node:20"
    - "test:docker://node:20"
    - "deploy:kubernetes://kubectl:latest"

Menggunakan Labels di Workflow

jobs:
  build:
    runs-on: node-20
    
  test:
    runs-on: ubuntu-latest
    
  deploy:
    runs-on: production

Troubleshooting

Runner Tidak Connect

Masalah: Runner status offline

Solusi:

# Check network connectivity
curl -I https://gitea.example.com

# Check runner logs
act_runner daemon --debug

# Verify registration
act_runner list

Job Stuck di Queue

Masalah: Jobs tidak dieksekusi

Solusi:

• Periksa label matching antara workflow dan runner
• Check runner capacity
• Verify runner status di Gitea UI

Docker Permission Error

Masalah: Permission denied untuk Docker socket

Solusi:

# Add user ke docker group
sudo usermod -aG docker gitea-runner

# Atau run dengan sudo (tidak direkomendasikan)
sudo act_runner daemon

Disk Space Issues

Masalah: Runner kehabisan disk space

Solusi:

# Clean Docker images
docker system prune -a -f

# Clean runner cache
rm -rf /tmp/actions/*

# Monitor disk usage
df -h

Security Best Practices

1. Isolasi Runner

• Jalankan runner di dedicated machines/containers
• Gunakan non-root user
• Implement network segmentation

2. Resource Limits

container:
  resources:
    memory: "2Gi"
    cpu: "2"
  limits:
    memory: "4Gi"
    cpu: "4"

3. Secrets Management

• Jangan log secrets
• Gunakan masked variables
• Rotate registration tokens

4. Update Regular

# Update runner binary
wget https://dl.gitea.com/act_runner/latest/act_runner-linux-amd64
sudo systemctl stop gitea-runner
sudo mv act_runner-linux-amd64 /usr/local/bin/act_runner
sudo systemctl start gitea-runner

Monitoring Runner

Health Check Script

#!/bin/bash
# runner-health-check.sh

RUNNER_STATUS=$(systemctl is-active gitea-runner)

if [ "$RUNNER_STATUS" != "active" ]; then
    echo "Runner is not running, attempting restart..."
    systemctl restart gitea-runner
    
    # Send notification
    curl -X POST https://alerts.example.com/webhook \
      -d "Runner down, restarted"
fi

Metrics Collection

Integrate dengan Prometheus:

# prometheus.yml
scrape_configs:
  - job_name: 'gitea-runner'
    static_configs:
      - targets: ['localhost:9091']

Kesimpulan

Gitea Runner adalah komponen krusial dalam pipeline CI/CD. Dengan setup yang proper:

• ✅ Reliable job execution
• ✅ Scalable infrastructure
• ✅ Flexible executor options
• ✅ Secure isolated environments

Next: Implementasi workflow files untuk Docusaurus project.