This repository uses ubuntu:questing as the base image for Chrome runner containers. This is a pre-release version of Ubuntu (25.10) chosen for access to the latest system libraries and browser dependencies.
CVE Mitigation Strategy:
- Many CVEs in Node.js, npm, and transitive dependencies cannot be patched directly due to upstream packaging.
- We use npm
overridesand local installs to patch all app-level dependencies. - CVEs present only in npm's internal modules are documented and monitored; they do not affect runtime security for the runner or browser tests.
- All images are scanned with Trivy and results are saved to
test-results/docker/for auditability.
Security Note:
If you require a fully supported, production-grade image, use a stable Ubuntu LTS release (e.g., ubuntu:24.04). See DEPLOYMENT.md for migration instructions.
A comprehensive, production-ready GitHub Actions self-hosted runner solution with monitoring, scaling, and security features.
Note: Documentation workflows and repo prompts were recently improved — see
.github/prompts/Wiki-Readme.prompt.md and docs/examples/update-docs-example.md for guidance on updating docs to match code changes.
| Component | Standard Runner | Chrome Runner | Status |
|---|---|---|---|
| Image Version | v2.0.9 | v2.0.9 | ✅ Latest |
| GitHub Actions Runner | v2.328.0 | v2.328.0 | ✅ Latest |
| Base OS | Ubuntu 25.10 Questing | Ubuntu 25.10 Questing | ✅ Supported/Pre-release |
| Node.js | 24.7.0 | ✅ Chrome Only | |
| Python | 3.10+ | 3.10+ | ✅ Latest |
| Playwright | - | v1.55.0 | ✅ Latest |
| Cypress | - | v15.1.0 | ✅ Security Fixed |
| Chrome | - | 140.0.7339.80 | ✅ Latest |
📋 For detailed version information, see Version Overview
- ✅ VDB-216777/CVE-2020-36632: Flat package vulnerability patched (
flat@5.0.2) - ✅ CVE-2025-9288: Cypress SHA.js vulnerability patched (
sha.js@2.4.12) - ✅ CVE-2024-37890: WebSocket DoS vulnerability patched (
ws@8.17.1) - ✅ Trivy Security Scanning: Automated weekly vulnerability scans (filesystem, main runner, Chrome runner)
- ✅ Container Hardening: Non-root execution, minimal attack surface
- ✅ Workflow Sync: All security scan jobs (
security-scan,security-container-scan,security-chrome-scan) are present in.github/workflows/ci-cd.ymland must be kept in sync across all branches. Usegit diff develop .github/workflows/ci-cd.ymlto verify parity before merging. If you see a warning about missing scan jobs, update and sync your workflow files, then re-run the workflow.
- Containerized Runners: Docker-based runners with multi-platform support (amd64/arm64)
- Chrome Runner: Specialized environment for web UI testing and browser automation
- Auto-scaling: Dynamic scaling based on workload demands using Docker Compose
- Monitoring: Prometheus metrics and Grafana dashboards for performance tracking
- Security: Comprehensive vulnerability scanning, security patches, and container hardening
- CI/CD Integration: Automated building, testing, and deployment with GitHub Actions
- High Availability: Health checks, automatic restarts, and failover mechanisms
- Multi-Environment: Support for dev, staging, and production environments
- Cache Optimization: Persistent volume caching for build artifacts and dependencies
- Security Scanning: Weekly Trivy scans (filesystem, container, Chrome runner) with automated SARIF reporting and GitHub Security tab integration
- Architecture Enforcement: Chrome runner image only supports
linux/amd64(x86_64). Builds on ARM (Apple Silicon) will fail with a clear error.
-- ✅ Applied critical security patches for prototype pollution and DoS vulnerabilities -- ✅ Optimized Docker image sizes with comprehensive cache cleaning -- ✅ Enhanced Chrome Runner with latest Playwright (1.55.0), Cypress (15.1.0), and Chrome (140.0.7339.80) -- ✅ Standardized Docker build contexts for consistent CI/CD pipeline execution -- ✅ Implemented automated security advisory workflow with Trivy scanning (filesystem, container, Chrome runner) -- ✅ All security scan jobs and workflow files are now kept in sync across branches for reliable code scanning and compliance
# Build the Chrome runner image (amd64 only)
docker buildx build --platform linux/amd64 -f docker/Dockerfile.chrome -t github-runner:chrome-latest .
# Start the runner with Docker Compose
docker compose -f docker/docker-compose.chrome.yml up -dNote: The Chrome runner image is only supported on
linux/amd64. If you attempt to build or run on ARM, the build will fail.
gh repo clone GrammaTonic/github-runner
cd github-runnerwget https://github.com/GrammaTonic/github-runner/archive/v2.0.2.tar.gz
tar -xzf v2.0.2.tar.gz
cd github-runner-2.0.2Pre-built Docker images are available for each release:
# Standard Runner (latest)
docker pull ghcr.io/grammatonic/github-runner:v2.0.2
# Chrome Runner (latest)
docker pull ghcr.io/grammatonic/github-runner-chrome:v2.0.2
# Development versions
docker pull ghcr.io/grammatonic/github-runner:develop
docker pull ghcr.io/grammatonic/github-runner-chrome:develop
# Semantic versioning
docker pull ghcr.io/grammatonic/github-runner:2.0.2
docker pull ghcr.io/grammatonic/github-runner:2.0
docker pull ghcr.io/grammatonic/github-runner:2- Docker 20.10+ and Docker Compose v2
- GitHub Personal Access Token with repo permissions
- (Optional) Kubernetes cluster for advanced deployment
- (Optional) Cloud provider account for remote deployment
📖 For detailed setup instructions, see our comprehensive Quick Start Guide
For the fastest deployment experience:
git clone https://github.com/GrammaTonic/github-runner.git
cd github-runner
./scripts/quick-start.shThe interactive script will guide you through:
- ✅ Runner type selection (Standard, Chrome, or Both)
- ✅ Prerequisite checks (Docker, permissions)
- ✅ Environment configuration with validation
- ✅ Automatic runner deployment
- ✅ Health verification and troubleshooting
- Standard Runner: General CI/CD with Docker, Node.js, Python
- Chrome Runner: UI testing with Chrome, Selenium, Playwright
- Both Runners: Deploy both types with separate configurations
git clone https://github.com/GrammaTonic/github-runner.git
cd github-runner
cp config/runner.env.example config/runner.envEdit config/runner.env:
# Required
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
GITHUB_REPOSITORY=owner/repo
# Optional
RUNNER_LABELS=self-hosted,docker,linux
RUNNER_NAME_PREFIX=runner
ENVIRONMENT=production# Production setup (recommended)
docker compose -f docker/docker-compose.production.yml up -d
# Scale runners based on demand
docker compose -f docker/docker-compose.production.yml up -d --scale github-runner=2 --scale github-runner-chrome=1# Check runner status
docker compose -f docker/docker-compose.production.yml ps
# View logs
docker compose -f docker/docker-compose.production.yml logs -f github-runner
# Check runner registration in GitHub
docker compose -f docker/docker-compose.production.yml logs github-runner | grep "Listening for Jobs"Specialized runner for browser automation and web UI testing with 60% performance improvement.
- ✅ Google Chrome Stable + automatically matched ChromeDriver
- ✅ Testing Frameworks: Playwright, Cypress, Selenium pre-installed
- ✅ Resource Isolation: Dedicated browser processes prevent contention
- ✅ Performance: 60% faster web UI tests vs standard runners
- ✅ Scaling: Horizontal scaling for parallel test execution
# Build and deploy Chrome Runner
./scripts/build-chrome.sh --push
docker-compose -f docker/docker-compose.chrome.yml up -d
# Scale for parallel testing
docker-compose -f docker/docker-compose.chrome.yml up -d --scale chrome-runner=3jobs:
ui-tests:
runs-on: [self-hosted, chrome, ui-tests]
steps:
- uses: actions/checkout@v4
- name: Run Playwright tests
run: npx playwright test
- name: Run Cypress tests
run: npx cypress run# Chrome Runner specific environment
CHROME_RUNNER_LABELS=chrome,ui-tests,browser
HEADLESS_CHROME=true
CHROME_SANDBOX=false📚 Full Documentation: Chrome Runner Wiki
github-runner/
├── .github/ # GitHub Actions workflows
├── cache/ # Local cache directories
├── config/ # Configuration templates
├── docker/ # Container configurations
├── docs/ # Documentation
├── monitoring/ # Health checks and monitoring
├── scripts/ # Automation scripts
└── README.md # This file
Edit config/runner.env:
| Variable | Description | Example | Required |
|---|---|---|---|
GITHUB_TOKEN |
GitHub PAT with repo access | ghp_xxxxxxxxxxxx |
✅ |
GITHUB_REPOSITORY |
Target repository | owner/repo |
✅ |
RUNNER_NAME_PREFIX |
Prefix for runner names | runner |
❌ |
RUNNER_LABELS |
Custom runner labels | self-hosted,docker |
❌ |
ENVIRONMENT |
Environment designation | production |
❌ |
The build system uses environment variables or defaults:
# Override registry settings if needed
export DOCKER_REGISTRY=ghcr.io
export DOCKER_NAMESPACE=grammatonic
# Build with custom settings
./scripts/build.sh --push# Start with basic configuration (choose runner type)
docker compose -f docker/docker-compose.production.yml up -d# Install Docker (if needed)
curl -fsSL https://get.docker.com | sh
# Clone and configure
git clone https://github.com/GrammaTonic/github-runner.git
cd github-runner
cp config/runner.env.example config/runner.env
# Edit config/runner.env with your settings
# Deploy standard runners
docker compose -f docker/docker-compose.production.yml up -d
# Or deploy Chrome runners for UI testing
docker compose -f docker/docker-compose.chrome.yml up -d# Check runner health
curl http://localhost:8080/health
# Prometheus metrics
curl http://localhost:9090/metrics
# Grafana dashboard
open http://localhost:3000# Scale up
docker compose -f docker/docker-compose.yml up -d --scale runner=5
# Scale down
docker compose -f docker/docker-compose.yml up -d --scale runner=1# Pull latest images
docker compose -f docker/docker-compose.yml pull
# Restart services
docker compose -f docker/docker-compose.yml up -dRunner not appearing in GitHub:
# Check logs
docker compose logs runner
# Verify token permissions
# Token needs 'repo' scope for private reposHigh resource usage:
# Monitor resources
docker stats
# Adjust compose file resource limits if needed
# Edit docker/docker-compose.production.yml or docker/docker-compose.chrome.yml# Enable debug logging
echo "RUNNER_DEBUG=1" >> config/runner.env
# Restart runners
docker compose logs -f runnerThis project includes comprehensive security scanning and monitoring:
- Weekly Vulnerability Scans: Automated Trivy scans every Monday
- Multi-Target Analysis: Filesystem, container, and Chrome runner scanning
- GitHub Security Integration: Results uploaded to Security tab (not cluttering issues)
- SARIF Format: Rich vulnerability data with remediation guidance
- Container Security: Regular base image updates and vulnerability patches
- Dependency Scanning: Automated detection of vulnerable packages
- Secret Management: Secure token handling and environment isolation
- Security Policies: Defined security standards and response procedures
- Security Tab: Go to repository's Security tab → Code scanning
- Workflow Artifacts: Download detailed reports from Actions → Security Advisory Management
- Weekly Summaries: Automated summary reports with priority actions
Note: Security vulnerabilities are managed through GitHub's Security tab, not through GitHub Issues, keeping your project issues clean and organized.
- 📖 Documentation
- 📊 Version Overview - Comprehensive version tracking and security status
- ⚙️ GitHub Actions Workflows
- 🐛 Issue Tracker
- 💬 Discussions
We welcome contributions! Please see our Contributing Guide for details.
# Fork and clone
git clone https://github.com/yourusername/github-runner.git
cd github-runner
# Switch to develop branch (integration branch)
git checkout develop
git pull origin develop
# Create feature branch from develop
git checkout -b feature/amazing-feature
# Make changes and test
make test
# Submit pull request to develop branchImportant: All regular development work should be done on feature branches created from develop and merged into develop via pull requests. Never commit directly to main. Hotfixes may be created from main when necessary and must be merged back into develop afterwards.
This project is licensed under the MIT License - see the LICENSE file for details.
- GitHub Actions team for the self-hosted runner API
- Docker community for containerization best practices
- Prometheus and Grafana teams for monitoring solutions
⭐ If this project helps you, please consider giving it a star on GitHub!
- Playwright screenshot artifact upload now copies from container to host for reliable CI/CD artifact collection
- Image verification added for both Chrome and normal runners in CI/CD workflows
- Diagnostics and health checks improved for runner startup and container validation
- Chrome runner documentation updated for Playwright, Cypress, Selenium, and browser automation best practices
- Normal runner Dockerfile and entrypoint improved for diagnostics and healthcheck reliability
- All documentation blocks, examples, and API docs synced with latest code and workflow changes
See docs/README.md and docs/chrome-runner.md for full details.
