Common Issues

🔧 Runner Registration Issues

Issue: "Runner registration failed"

# Test token manually
curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user
# Required scopes for private repos
# - repo (full control)
# - workflow (update workflows)

# Correct format
GITHUB_REPOSITORY=owner/repository-name
# Common mistakes
GITHUB_REPOSITORY=https://github.com/owner/repo # ❌
GITHUB_REPOSITORY=owner/repo.git # ❌

# Check token expiration
gh auth status
# Regenerate if expired
gh auth refresh

Issue: "Runner name already exists"

# Add timestamp or hostname
RUNNER_NAME=runner-$(hostname)-$(date +%s)
# Use container ID
RUNNER_NAME=runner-$(cat /proc/self/cgroup | head -1 | cut -d/ -f3 | cut -c1-12)

# List current runners
gh api repos/OWNER/REPO/actions/runners
# Remove specific runner
gh api repos/OWNER/REPO/actions/runners/RUNNER_ID -X DELETE

🐳 Docker Issues

Issue: "Docker daemon not accessible"

# Add user to docker group
sudo usermod -aG docker $USER
# Reload group membership
newgrp docker
# Test access
docker ps

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker
# Verify Docker is running
docker version

volumes:
 - /var/run/docker.sock:/var/run/docker.sock:ro

Issue: "Out of disk space"

# Remove unused containers
docker container prune -f
# Remove unused images
docker image prune -a -f
# Remove unused volumes
docker volume prune -f
# Complete cleanup
docker system prune -a --volumes -f

# Check Docker disk usage
docker system df
# Check container sizes
docker ps -s
# Check volume sizes
docker volume ls

services:
 runner:
 logging:
 driver: "json-file"
 options:
 max-size: "10m"
 max-file: "3"

🔐 Authentication Issues

Issue: "Token authentication failed during job"

# In your workflow
steps:
 - uses: actions/checkout@v4
 with:
 token: ${{ secrets.GITHUB_TOKEN }}

# In runner entrypoint
git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"

# Token needs 'repo' scope for private repositories
# Token needs 'public_repo' scope for public repositories

📊 Performance Issues

Issue: "Slow job execution"

deploy:
 resources:
 limits:
 memory: 4g
 cpus: "2.0"
 reservations:
 memory: 1g
 cpus: "0.5"

# Use multi-stage builds
FROM node:16-alpine as builder
COPY package*.json ./
RUN npm ci --only=production
FROM node:16-alpine as runtime
COPY --from=builder /app/node_modules ./node_modules

volumes:
 - build_cache:/root/.cache
 - deps_cache:/root/.npm

Issue: "Memory leaks"

# Check container memory
docker stats --no-stream
# Check system memory
free -h
# Monitor over time
watch -n 5 'docker stats --no-stream'

deploy:
 resources:
 limits:
 memory: 2g

restart: unless-stopped
healthcheck:
 test: ["CMD", "pgrep", "Runner.Listener"]
 interval: 30s
 timeout: 10s
 retries: 3

🌐 Network Issues

Issue: "Cannot reach GitHub API"

# Test DNS resolution
nslookup api.github.com
# Test HTTPS connectivity
curl -v https://api.github.com
# Test with proxy
curl -x proxy.company.com:8080 https://api.github.com

# Environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,10.0.0.0/8
# Docker proxy configuration

# Required ports
# 443 (HTTPS) - api.github.com
# 443 (HTTPS) - github.com
# 443 (HTTPS) - objects.githubusercontent.com

🔄 Scaling Issues

Issue: "Runners not scaling properly"

# Ensure consistent labels
RUNNER_LABELS=self-hosted,linux,x64,docker
# Verify in GitHub UI
# Settings → Actions → Runners

# Scale up
docker compose up -d --scale runner=5
# Check running containers
docker ps --filter "name=runner"

# Check queued jobs
gh api repos/OWNER/REPO/actions/runs --jq '.workflow_runs[] | select(.status=="queued")'

🔍 Debugging Tools

Container Debugging

# Access container shell
docker exec -it github-runner_runner_1 /bin/bash
# Check container logs
docker logs github-runner_runner_1 --tail 100 -f
# Inspect container configuration
docker inspect github-runner_runner_1
# Check resource usage
docker stats github-runner_runner_1

Log Analysis

# Search for specific errors
docker logs runner 2>&1 | grep -i error
# Monitor real-time logs
docker logs runner -f --tail 50
# Export logs for analysis
docker logs runner > runner-logs-$(date +%Y%m%d).txt

System Diagnostics

# Check system resources
htop
iotop
netstat -tulpn
# Check Docker status
systemctl status docker
journalctl -u docker.service --since "1 hour ago"
# Check file descriptors
lsof | grep docker

📞 Getting Help

Information to Gather

# Operating system
uname -a
# Docker version
docker version
# Docker Compose version
docker compose version

# Environment variables (redact secrets)
env | grep -E "GITHUB|RUNNER|DOCKER" | sed 's/TOKEN=.*/TOKEN=***/'
# Docker Compose configuration
docker compose config

# Container logs
docker logs runner --tail 100
# System logs
journalctl -u docker.service --since "1 hour ago"

Support Channels

🔄 Related Pages