glefer/github-runner-manager repository overview

⁠Github runner manager

⁠Short description

• Lightweight CLI tool to manage GitHub Actions self-hosted runners using Docker. Build and run custom runner images, start/stop/remove runners, and check base runner image updates.

⁠Key features

• Manage runner lifecycle (start, stop, remove, list) via CLI.
• Build custom runner images from project Dockerfiles.
• Dynamic registration tokens via GitHub API (requires personal token).
• Works by communicating with the Docker daemon over the host socket.

⁠Quick usage (Docker)

# Pull from Docker Hub
docker pull glefer/github-runner-manager:latest

# Run (mount Docker socket and config/config dir)
docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/runners_config.yaml:/app/runners_config.yaml \
  -v $(pwd)/config:/app/config:ro \
  glefer/github-runner-manager:latest list-runners

⁠Environment

• Set a GitHub personal token for registration API calls: GITHUB_TOKEN (or set github_personal_token in the config file).
• See configuration example in runners_config.yaml.

⁠Configuration

• Default configuration file path: runners_config.yaml — example/structure in README.md.
• Custom Dockerfiles for runners live under config and are referenced by the config.

⁠CLI commands

• build-runners-images, start-runners, stop-runners, remove-runners, check-base-image-update, list-runners (see entrypoint in main.py and commands wiring in src/presentation/cli/commands.py).

⁠Build & tags

• Image tags produced by CI: glefer/github-runner-manager:latest and versioned tags (see CI workflow /.github/workflows/ci.yml).
• Local build: docker build -t glefer/github-runner-manager:local .

⁠Notes & security

• The container must mount /var/run/docker.sock to control Docker on the host — this grants full Docker access to the container.
• Never commit or share GitHub personal tokens; prefer least-privilege tokens (scopes: admin:org or repo).