This repository was archived by the owner on Jun 8, 2026. It is now read-only.
-
-
Notifications
You must be signed in to change notification settings - Fork 0
Installation Guide
GrammaTonic edited this page Sep 4, 2025
·
2 revisions
This guide will walk you through installing and setting up GitHub Actions Self-Hosted Runner step by step.
Before starting, ensure you have:
- Docker Engine 20.10+ installed
- Docker Compose 2.0+ installed
- Git installed
- GitHub repository admin access
- At least 2GB free disk space
- Internet connectivity
- CPU: 1 vCPU
- Memory: 2GB RAM
- Disk: 10GB free space
- OS: Linux (Ubuntu 20.04+), macOS, or Windows with WSL2
- CPU: 2+ vCPUs
- Memory: 4GB+ RAM
- Disk: 50GB+ free space (for build caches)
- Network: Stable internet connection (1Mbps+)
# Using Git git clone https://github.com/GrammaTonic/github-runner.git cd github-runner # Using GitHub CLI gh repo clone GrammaTonic/github-runner cd github-runner
# Copy configuration template cp config/runner.env.template config/runner.env # Edit configuration nano config/runner.env
Required environment variables:
# GitHub Configuration GITHUB_TOKEN=ghp_your_token_here GITHUB_REPOSITORY=owner/repo-name RUNNER_NAME=my-runner-01 # Runner Configuration RUNNER_LABELS=self-hosted,docker,linux RUNNER_GROUP=default
- Go to GitHub Settings β Developer settings β Personal access tokens
- Generate new token with permissions:
-
repo(for private repositories) -
workflow(to access Actions)
-
- Copy token to
GITHUB_TOKENinconfig/runner.env
# Start basic runner docker compose -f docker/docker-compose.yml up -d # Start with monitoring (recommended) docker compose -f docker/docker-compose.yml --profile monitoring up -d
# Check runner status docker compose logs runner # Verify in GitHub # Go to Settings β Actions β Runners in your repository
# Build custom image docker build -t my-github-runner ./docker # Update docker-compose.yml to use custom image # image: my-github-runner:latest
# Scale to 3 runners
docker compose -f docker/docker-compose.yml up -d --scale runner=3# Create production environment file cp config/runner.env config/production.env # Configure for production DOCKER_BUILDKIT=1 COMPOSE_PROJECT_NAME=github-runner-prod RUNNER_MEMORY_LIMIT=4g RUNNER_CPU_LIMIT=2.0 # Deploy with production settings docker compose -f docker/docker-compose.yml --env-file config/production.env up -d
| Variable | Description | Default | Required |
|---|---|---|---|
GITHUB_TOKEN |
GitHub personal access token | - | β |
GITHUB_REPOSITORY |
Target repository (owner/name) | - | β |
RUNNER_NAME |
Unique runner identifier | hostname | β |
RUNNER_LABELS |
Comma-separated labels | self-hosted,docker | β |
RUNNER_GROUP |
Runner group name | default | β |
RUNNER_WORK_DIR |
Working directory | /workspace | β |
| Variable | Description | Default |
|---|---|---|
RUNNER_MEMORY_LIMIT |
Memory limit per runner | 2g |
RUNNER_CPU_LIMIT |
CPU limit per runner | 1.0 |
DOCKER_NETWORK |
Docker network name | github-runner-network |
COMPOSE_PROJECT_NAME |
Docker Compose project | github-runner |
Docker not found:
# Install Docker curl -fsSL https://get.docker.com | sh # Add user to docker group sudo usermod -aG docker $USER newgrp docker
Permission denied:
# Fix permissions sudo chown -R $USER:$USER /var/run/docker.sock
Token authentication failed:
- Verify token has correct permissions
- Check repository name format (owner/repo)
- Ensure token hasn't expired
Runner not appearing:
# Check logs docker compose logs runner # Verify network connectivity curl -s https://api.github.com/user
After successful installation:
- Quick Start Guide - Run your first workflow
- Docker Configuration - Customize Docker setup
- Security Configuration - Secure your runners
- Production Deployment - Production checklist
- Issues: Check Common Issues
- Documentation: Browse the wiki home
- Support: Open an issue on GitHub