kerklangsi/github-runner repository overview

⁠🚀 GitHub Runner Manager v4.0.3

A modern, full-stack Web GUI and Docker container manager for GitHub Actions self-hosted runners. Easily provision, monitor, control, and update multiple GitHub runner instances from a high-performance web dashboard.

⁠✨ Features

• 🌐 Modern Web Dashboard: React + Express UI running on port 3000 for managing all runner instances in real-time.
• ⚡ Rapid Runner Provisioning: Provision repository or organization runners using Personal Access Tokens (PAT) or one-time registration tokens.
• 🛑 Automatic Workflow Run Cancellation: Gracefully sends SIGINT signals to the runner listener on Stop/Restart to inform GitHub Actions of cancellation, and dispatches cancellation requests via GitHub REST API on Start/Restart.
• 📜 Live Workflow Execution Logging (job-logs.txt): Real-time harvester captures verbatim Azure blob step output from _diag/pages before runner purging, complete with microsecond timestamps, ANSI colors, and ##[group] markers.
• 🔄 Dual Log Inspection: Toggle instantly between Live Workflow Step Output (job-logs.txt) and Runner Daemon Lifecycle logs (runner.log) with search and one-click file download.
• 📦 Unified Persistent Tool Cache: Automatically caches toolchains (Node.js, Python via setup-python/setup-node) and packages (pip wheels, Playwright browsers, npm) into a single persistent cache volume (/home/runner/.cache ➔ /opt/hostedtoolcache), eliminating duplicate downloads across workflows.
• 📁 Decoupled Shared Repository Data: Dedicated persistent storage (/opt/shared_data) organized by repository, with automatic workspace pre-linking for authentication tokens and credentials.
• 🖥️ Built-in Interactive Web Terminal: Execute diagnostics directly from the web shell.
• 📊 Real-time Hardware Telemetry: Monitor CPU, RAM, Disk space, and network bandwidth cgroup metrics.
• 📜 Live Log Streaming: Inspect isolated runner logs and global container buffers with real-time level filtering (INFO, DEBUG, WARN, ERROR).
• 📋 Workflow Execution Tracking: Track recent GitHub Actions workflow runs and completion states with direct "View Log" navigation.
• 📁 Files & Storage Explorer: Built-in web explorer with interactive breadcrumbs to browse, preview, and download files across /opt/shared_data, runner workspaces, and /app/data.
• 🔄 Isolated Session Logs & Automated Archive Retention: Clean fresh logs on container startup and runner restarts, automatically archiving previous sessions into /app/data/archive/ and <runnerDir>/logs/archive/, with configurable pruning schedules (never, daily, weekly, monthly, custom days) and unfiltered workflow step outputs in DEBUG mode.
• ⚡ Two-Tier Watchdog & Auto-Start: Global master switch with per-runner watchdog recovery and optional automatic runner startup on container boot.
• 🛡️ Alert Webhooks: Discord/Slack webhook notifications on runner crashes, offline events, or watchdog recoveries.
• 📋 Universal Clipboard Compatibility: Robust clipboard copy fallback supporting plain HTTP LAN IP access.
• 💾 Config Backup & Restore: Export and import system configurations as JSON.
• 🎨 Dark / Light Themes & Custom Avatars: Customize profile avatar image URLs or base64 uploads.
• 🚀 Automatic Update Checker: Notifies users in-app when new releases are pushed to GitHub or Docker Hub.
• 🖥️ Universal Docker Compose: Compatible with standard Docker, Docker Compose, Portainer, CasaOS, and ZimaOS.

⁠⚡ Quickstart

⁠Option 1: Docker Compose (Recommended)

Run with Docker Compose using docker-compose.yml⁠:

name: github-runner

services:
  github-runner:
    image: kerklangsi/github-runner:latest
    container_name: github-runner-manager
    restart: unless-stopped
    network_mode: bridge
    ports:
      - target: 3000
        published: 3000
        protocol: tcp
    volumes:
      - type: bind
        source: /var/run/docker.sock
        target: /var/run/docker.sock
      - type: bind
        source: /DATA/AppData/github-runner/data
        target: /app/data
      - type: bind
        source: /DATA/AppData/github-runner/runner
        target: /opt/github-runner
      - type: bind
        source: /DATA/AppData/github-runner/shared_data
        target: /opt/shared_data
      - type: bind
        source: /DATA/AppData/github-runner/cache
        target: /home/runner/.cache

Launch with:

docker compose up -d

Access the Web Dashboard at http://localhost:3000 (or http://<your-server-ip>:3000).

⁠Option 2: ZimaOS / CasaOS Manual Install

1. Open ZimaOS App Store or CasaOS App Store.
2. Click Manual Install or Custom Install.
3. Import or paste docker-compose.yml⁠.
4. Click Install.

⁠Option 3: Docker Run

Run directly via docker run:

docker run -d \
  --name github-runner-manager \
  --restart unless-stopped \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /DATA/AppData/github-runner/data:/app/data \
  -v /DATA/AppData/github-runner/runner:/opt/github-runner \
  -v /DATA/AppData/github-runner/shared_data:/opt/shared_data \
  -v /DATA/AppData/github-runner/cache:/home/runner/.cache \
  kerklangsi/github-runner:latest

Access the Web Dashboard at http://localhost:3000 (or http://<your-server-ip>:3000).

⁠🛠️ Environment Variables

⁠🔒 Security & Persistence

• All runner metadata, encrypted access tokens, system logs, and custom avatars are safely persisted inside the /app/data Docker volume mount.
• Password change forms in the Settings tab allow changing the default admin credentials immediately.

⁠📄 License

Distributed under the MIT License. See LICENSE⁠ for more information.

Made with ❤️ by Kerk Langsi⁠.