https://github.com/soulteary/runner-fleet

GitHub Actions Runner Manager, a lightweight toolkit to provision, scale, and manage a fleet of GitHub self-hosted runners with ease. / 轻量工具，一键部署、扩容并统一管理多台 GitHub 自托管 Runner。
https://github.com/soulteary/runner-fleet

cicd github github-actions github-runner github-runners self-hosted self-hosted-runner

Last synced: 11 days ago
JSON representation

GitHub Actions Runner Manager, a lightweight toolkit to provision, scale, and manage a fleet of GitHub self-hosted runners with ease. / 轻量工具，一键部署、扩容并统一管理多台 GitHub 自托管 Runner。

• Host: GitHub
• URL: https://github.com/soulteary/runner-fleet
• Owner: soulteary
• License: mit
• Created: 2026-02-17T02:05:38.000Z (4 months ago)
• Default Branch: main
• Last Pushed: 2026-02-24T06:32:28.000Z (4 months ago)
• Last Synced: 2026-02-24T12:51:17.387Z (4 months ago)
• Topics: cicd, github, github-actions, github-runner, github-runners, self-hosted, self-hosted-runner
• Language: Go
• Homepage: https://soulteary.com/2026/02/18/use-docker-to-natively-deploy-github-actions-runner-by-fleet.html
• Size: 594 KB
• Stars: 11
• Watchers: 0
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Security: docs/security.md

Awesome Lists containing this project

README

          
# Runner Fleet - GitHub Actions Runner Manager

**文档 (Docs):** [中文](docs/zh/) · [Français](docs/fr/) · [Deutsch](docs/de/) · [한국어](docs/ko/) · [日本語](docs/ja/)

![](.github/assets/fleet.jpg)

HTTP management UI built with Golang Echo to view and manage multiple self-hosted GitHub Actions Runners on one machine. YAML-based config, no database required.

![](.github/assets/preview.jpg)

## Highlights

- **Zero database**: YAML-only config, no external deps; config is your backup and easy to version.

- **Web one-stop**: Add, register, start/stop, edit, and view status in the UI—no SSH or manual `config.sh`.

- **Auto install & register**: In "Quick Add" enter a token to auto-download the runner, register, and start; paste `./config.sh --url ... --token ...` from GitHub to parse and fill the form.

- **Container-first**: Docker / docker-compose out of the box; DinD and host-socket for in-job Docker; optional **container mode** (one runner per container) with Manager controlling lifecycle and status.

- **Self-heal & troubleshoot**: ~15s after start, registered but stopped runners are started; periodic check every 5 minutes; in container mode, `status=unknown` shows a structured probe (error type, check/fix commands) for copy-paste troubleshooting or start/stop self-heal.

- **Observable**: Registration result is written and shown in the UI; optional PAT (`.github_check_token`) to periodically verify runners appear in GitHub's list, synced to the UI.

## Features

- **View**: List all runners, status (installed/unregistered/missing dir), running or not; view full config per runner.

- **Edit**: Change subpath, target type, target, labels (name is read-only).

- **Quick Add**: Name + target (org/repo) + optional token; one-click add and optional auto-register.

- **Delete**: Remove from config (does not delete disk).

- **Start/Stop**: Start or stop registered runners.

- **Container mode** (optional): One runner per container; Manager starts/stops via Docker; runner image tag uses `-runner` suffix.

## Quick start

```bash

mkdir -p config && cp config.yaml.example config/config.yaml

# Edit config/config.yaml: set runners.base_path to /app/runners

# On host: mkdir -p runners && chown 1001:1001 config runners

docker network create runner-net 2>/dev/null || true

docker compose up -d

```

Open http://localhost:8080. The default image tag is the stable release (e.g. v1.0.0). For more options (docker run, DinD, container mode, using `main` or other tags) see the [User Guide](docs/guide.md). Health: `GET /health`; version: `GET /version`.

## Use cases

- **Personal / team**: One machine as self-hosted runners for multiple repos or orgs; manage via Web UI, no need to remember CLI.

- **Internal CI**: Deploy on internal network; use DinD (isolated) or host-socket (shared with host) when jobs need Docker; runners recover after Manager or DinD restart.

- **Isolation & traceability**: Container mode gives one container per runner with clear boundaries; combine with registration result and GitHub visibility check to verify runners.

## Documentation

- **[User Guide](docs/guide.md)** — Deployment (Docker/docker-compose), config, adding runners, security & troubleshooting

- **[Development & Build](docs/development.md)** — Go build, local debug, HTTP API, Makefile

## Other

CI / images / releases: [.github/workflows](.github/workflows).

MIT License — see [LICENSE](LICENSE).