https://github.com/maxpeterkaya/virtual-runner
Run self-hosted GitHub Runners in docker with resource limitations and scalability.
https://github.com/maxpeterkaya/virtual-runner
docker github runner
Last synced: 4 months ago
JSON representation
Run self-hosted GitHub Runners in docker with resource limitations and scalability.
- Host: GitHub
- URL: https://github.com/maxpeterkaya/virtual-runner
- Owner: maxpeterkaya
- Created: 2025-08-18T16:29:20.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-19T01:22:44.000Z (11 months ago)
- Last Synced: 2025-08-19T03:24:52.966Z (11 months ago)
- Topics: docker, github, runner
- Language: Dockerfile
- Homepage:
- Size: 7.81 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Dockerized GitHub Runner
This project aims to simplify the process of making a self hosted action runner by allowing the user to neatly limit system resources, ensure constant up-time, and enhance scalability.
## Roadmap
- Generate custom name, if not provided one, with helpful information like host, region, and platform.
- Structured logs (this is primarely just an idea and may not even be implemented)
## Capabilities
Currently only Linux is supported, however Mac and Windows will be soon also supported.
- Custom runner name (with randomly generated suffix to ensure uniqueness when horizontally scaling)
- Automatic clean-up
- Organization Runner
- Personal Repository Runner
## Getting Started
Per the ``docker-compose.yml`` file, use this template and fill-in the environment variables.
You can grab your runner token by going to your organization or personal repository **Settings** page, clicking on **Actions** and **Runners**, then **New self-hosted runner**.
Your token should in the **Configure** box. ex:
```bash
Configure
./config.sh --url https://github.com/maxpeterkaya/docker-runner --token YOUR_TOKEN
```
Copy YOUR_TOKEN then to the environment variable in the docker-compose file.
```yml
services:
runner:
image: ghcr.io/maxpeterkaya/docker-runner:latest
restart: always
environment:
- OWNER= # This can be just an org or a repo, eg. ORG: github | REPO: maxpeterkaya/docker-runner
- TOKEN= # This is your token you recieve from github when creating a new self hosted runner
- NAME= # This is your runner's name for easier distinction
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
reservations:
cpus: '0.3'
memory: 256M
```
Refer to the [docker compose reference](https://docs.docker.com/reference/compose-file/deploy/#resources) for more details about the resources configuration.