A lightweight, simple controller for GitHub Actions self-hosted runners
- Runs as a single Go daemon with a configuration file
- No dependencies on components such as Kubernetes or databases
- A small footprint and minimal stored state make setup and rebuilding easy
- Scales runners on demand
- Runners run as lightweight native processes on the host
- A configurable execution user provides basic privilege separation
- Manages multiple repositories and organizations together
- Share one host across multiple projects
- Fine-grained concurrency control through global and per-target scaling settings
By design, ghalet does not provide strict isolation between runners. It is intended for standalone, dedicated hosts, such as:
- High-performance dedicated build machines
- Single-purpose VMs
- Home servers, such as a Mac mini or a spare laptop
ghalet manages GitHub Actions Runner Scale Sets on Linux and macOS. It starts runner processes on demand and cleans up their runner directories and workspaces after confirming they have stopped.
When choosing an autoscaler for self-hosted runners, first consider the official Actions Runner Controller (ARC). ARC manages Runner Scale Sets on Kubernetes and is a natural choice if you already operate a Kubernetes cluster.
ghalet instead manages Runner Scale Sets with a single, lightweight Go daemon. It uses the actions/scaleset library, which is also used internally by ARC, to manage Runner Scale Sets. It runs on one host without Kubernetes or an external database. If you do not need multi-host orchestration, this keeps setup, operation and stored state small. It focuses on scaling runner processes on a single host; scaling the hosts themselves is out of scope.
ghalet starts runners as native OS processes and does not create VMs or containers.
Each runner is registered as ephemeral and executes a job,
but this does not isolate the execution environment: jobs running as the same
user share HOME, tools, caches and privileges. Use only trusted workflows,
not untrusted fork PRs or hostile code. We recommend setting runner.user to
a dedicated, non-root OS account with limited privileges.
Linux .deb/.rpm packages with a systemd unit and a GHCR container image
are also built for releases. See packages and containers
for installation, configuration, and updates.
Install with Homebrew:
brew install Songmu/tap/ghaletOr install with Go:
go install github.com/Songmu/ghalet/cmd/ghalet@latestSee getting started for host prerequisites and execution user requirements.
Follow getting started for authentication, configuration, a complete workflow, and your first job. It also covers macOS service setup with Homebrew. For ongoing operation, use systemd on Linux or launchd on macOS.
All commands accept --config PATH. A target is one Runner Scale Set
registration, identified by its scope, runner group and scale set name.
The local targetId is derived from that registration, not configured.
| Command | Purpose |
|---|---|
ghalet run |
Run the daemon in the foreground for all configured targets. |
| Command | Purpose |
|---|---|
ghalet apply |
Drain targets, reload configuration, and reconcile registrations, attempting to delete unused scale sets. |
ghalet config validate |
Validate configuration and local paths without contacting GitHub. |
ghalet app setup --scope OWNER/REPO --scale-set ghalet-runner |
Create and install a private GitHub App, save managed authentication, and print any required static target configuration. See App setup for organization scopes, SSH and resumption. |
ghalet credential set NAME --prompt |
Save an owner-only credential file and update managed defaults without rewriting static config. See ordinary credentials for App keys and replacement. |
These commands require Linux and root privileges and default to
/etc/ghalet/config.yaml.
| Command | Purpose |
|---|---|
ghalet systemd app setup --scope OWNER/REPO --scale-set ghalet-runner |
Set up an App with encrypted service credentials and the target's runtime key reference. See App setup. |
ghalet systemd credential set NAME --prompt |
Register an encrypted service PAT and update managed defaults. See credentials for App keys, automation and rotation. |
| Command | Purpose |
|---|---|
ghalet list |
List accessible daemons, management UIDs, sockets and running snapshots; filter with --config PATH. |
ghalet status [--fail-on-error] |
Read state, capacity and diagnostics; use --fail-on-error to exit nonzero for any diagnostic problem. |
ghalet gc [--dry-run] |
Clean verified stopped executions and expired logs; preview with --dry-run. |
ghalet --version prints the installed version. Management responses are
JSON, except for the App/credential setup instructions. Without --config, status,
apply, and gc automatically select the single accessible daemon; multiple
daemons require an explicit config. With none found, the per-user default
~/.config/ghalet/config.yaml is used, as it is for run and config validate.
See configuration apply and
diagnosis and cleanup
for exit codes, offline maintenance and deletion safeguards.
Host capacity defaults to two, with per-target limits and optional idle warm pools. Assigned jobs take priority. Atomic state files and kernel process identities support crash recovery; unverifiable executions retain capacity.
Runner archives are automatically downloaded for the pinned version and verified against official SHA-256 digests. Daemon stdout is JSONL; runner logs are archived before cleanup by default. See operations for retries, recovery and log policy.
Start with the documentation index, readable directly in the repository or on the documentation site. All guides are available in English and Japanese.
- Getting started: installation, authentication, your first workflow, and service setup.
- Authentication setup: method tradeoffs, minimum permissions, creation steps and credential rotation for PATs and GitHub Apps.
- Operations: authentication, configuration, execution environment, recovery, logs and systemd/launchd/Lima deployment.
- Example configuration and configuration schema.
See the contributor guide for development, testing, packaging, and documentation site maintenance.