ruriazz/gh-runner-kit repository overview

⁠GitHub Actions Self-Hosted Runner Kit

A production-ready Docker image for running GitHub Actions on your own infrastructure. Supports x64 architectures with optional SonarScanner integration.

⁠Features

✅ GitHub Actions Compatible - Full support for GitHub Actions workflows
✅ SonarQube Scanner - Optional integrated SonarScanner for code quality analysis
✅ Auto-Configuration - Automatic setup with GitHub registration tokens
✅ Health Checks - Built-in health monitoring
✅ Persistent Storage - Docker volume support for runner data
✅ Secure - Runs as unprivileged user by default

⁠Prerequisites

• Docker & Docker Compose
• GitHub Personal Access Token (PAT) with repo scope
• GitHub repository with Actions enabled

⁠Quick Start

⁠1. Clone or Copy Files

Get the docker-compose.yml and .env.example files:

curl -O https://raw.githubusercontent.com/ruriazz/gh-runner-kit/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/ruriazz/gh-runner-kit/main/.env.example
cp .env.example .env

⁠2. Configure Environment Variables

Edit .env with your GitHub credentials:

GITHUB_REPOSITORY=your-org/your-repo
GITHUB_TOKEN=ghp_your_personal_access_token_here
RUNNER_NAME=self-hosted-runner
RUNNER_LABELS=self-hosted,linux,x64

Get your GitHub Token:

1. Go to GitHub Settings → Developer settings → Personal access tokens⁠
2. Click "Generate new token"
3. Select scope: repo (full control of private repositories)
4. Copy the token and add to .env

⁠3. Start the Runner

docker-compose up -d

Check logs:

docker-compose logs -f github-runner

⁠4. Verify Runner Registration

Check your GitHub repository settings:

• Go to Settings → Actions → Runners
• Your runner should appear as "Online"

⁠Docker Compose Configuration

services:
  github-runner:
    image: ruriazz/gh-runner-kit:${IMAGE_TAG:-beta}
    container_name: github-runner
    restart: unless-stopped
    environment:
      # GitHub Configuration (REQUIRED)
      GITHUB_REPOSITORY: ${GITHUB_REPOSITORY}
      GITHUB_TOKEN: ${GITHUB_TOKEN}

      # Runner Configuration (OPTIONAL)
      RUNNER_NAME: ${RUNNER_NAME:-self-hosted-runner}
      RUNNER_LABELS: ${RUNNER_LABELS:-self-hosted,linux,x64}
      RUNNER_WORKDIR: ${RUNNER_WORKDIR:-_work}

      # SonarQube Configuration (OPTIONAL - only needed if INSTALL_SONAR=true)
      SONAR_HOST_URL: ${SONAR_HOST_URL:-}
      SONAR_TOKEN: ${SONAR_TOKEN:-}

      # Advanced Options
      RUNNER_ALLOW_RUNASROOT: ${RUNNER_ALLOW_RUNASROOT:-false}
      DISABLE_AUTO_UPDATE: ${DISABLE_AUTO_UPDATE:-false}

    volumes:
      # Persist runner data across restarts
      - runner-data:/actions-runner/_work

      # Optional: Mount Docker socket if workflows need Docker
      # - /var/run/docker.sock:/var/run/docker.sock

      # Optional: Mount additional workspace directories
      # - ./workspace:/workspace

    # Optional: Network configuration
    # networks:
    #   - runner-network

volumes:
  runner-data:
    driver: local

# Optional: Custom network
# networks:
#   runner-network:
#     driver: bridge

⁠Environment Variables

⁠Required

⁠Optional

⁠Advanced Usage

⁠Enable SonarScanner

Add to your .env:

INSTALL_SONAR=true
SONAR_HOST_URL=https://sonarqube.example.com
SONAR_TOKEN=your_sonar_token_here
SONAR_SCANNER_VERSION=8.0.1.6346

⁠Use Different Runner Version

RUNNER_VERSION=2.329.0

⁠Mount Docker Socket (for Docker-in-Docker workflows)

Uncomment in docker-compose.yml:

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

⁠Custom Network

Uncomment the network section in docker-compose.yml:

networks:
  runner-network:
    driver: bridge

⁠Using in GitHub Workflows

Once registered, use the runner in your workflows:

name: Build and Test

on: [push, pull_request]

jobs:
  build:
    runs-on: self-hosted  # Uses your custom runner
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Run tests
        run: npm test

Target specific runner:

runs-on: [self-hosted, linux, x64]

⁠Container Management

⁠View Logs

docker-compose logs -f github-runner

⁠Stop Runner

docker-compose stop

⁠Restart Runner

docker-compose restart

⁠Remove Runner

docker-compose down -v

This will also deregister the runner from GitHub.

⁠Health Checks

The image includes health monitoring that checks if the runner process is active every 30 seconds. View health status:

docker ps --filter "name=github-runner"

Look for (healthy) or (unhealthy) status.

⁠Troubleshooting

⁠Runner Won't Start

Check logs:

docker-compose logs github-runner

Common issues:

1. Invalid GitHub Token

   • Verify token has repo scope
   • Ensure token hasn't expired
   • Check GITHUB_REPOSITORY format: owner/repo

2. Token Permissions (Organization Repos)

   • Organization repositories need admin:org scope
   • Generate new token with proper permissions

3. Network Issues

   • Ensure container can reach GitHub API
   • Check firewall/proxy settings

⁠Runner Goes Offline

• Check container health: docker ps
• Restart: docker-compose restart
• Check disk space: docker exec github-runner df -h

⁠Permission Issues

Verify volumes have proper permissions:

docker exec github-runner ls -la /actions-runner/

⁠Security Considerations

⚠️ Important:

• Never commit .env with real tokens to version control
• Use GitHub's organization-level runners for sensitive data
• Regularly rotate PAT tokens
• Consider using deploy keys for repository-specific access
• Runner runs as unprivileged runner user by default

⁠Performance Tips

• Run on a machine with at least 2 CPU cores and 4GB RAM
• For resource-intensive workflows, use dedicated machines
• Use runner labels to route jobs appropriately
• Monitor runner logs for performance issues

⁠Supported Architectures

• x86_64 (Intel/AMD)

Architecture is auto-detected during build.

⁠License

This image is based on the official GitHub Actions Runner⁠.

⁠Support

For issues and questions:

• GitHub Issues⁠
• GitHub Discussions⁠

Version: beta
Last Updated: December 2025