- Go 99.2%
- Dockerfile 0.4%
- Makefile 0.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo/workflows | ||
| cmd | ||
| configs | ||
| deploy | ||
| docs | ||
| internal | ||
| .dockerignore | ||
| .gitignore | ||
| .golangci.yml | ||
| Dockerfile | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| openstack-discover | ||
| README.md | ||
forgejo-autoscale-runner
An autoscaler for Forgejo Actions, equivalent to GitLab Runner's autoscaler. It
watches a Forgejo instance for queued jobs, provisions cloud VMs on demand, runs
forgejo-runner on them (jobs execute in Docker, as usual), and tears the VMs
down when they go idle.
Providers: Scaleway, OVH, and Hetzner (European clouds).
Status: working. The control loop, Forgejo client, scaling logic and cloud-init are implemented and unit-tested. Both backends (Scaleway and OVH) are live-validated end to end against Forgejo 15 + forgejo-runner 12.11.1. See docs/features.md.
How it works
- Each tick the controller reads instance-wide demand and capacity once:
- demand:
GET /api/v1/admin/actions/runners/jobs, jobs withstatus: waiting - capacity:
GET /api/v1/admin/actions/runners,statusofidle/active
- demand:
- For each pool it computes a target instance count and reconciles:
- scale up: register an ephemeral runner (
POST .../runners), bake the credential into cloud-init, create a VM - scale down: delete VMs idle past
max_idle_time, plus finished ephemeral VMs and VMs that never booted
- scale up: register an ephemeral runner (
- cloud-init installs Docker and
forgejo-runnerand starts it. Jobs run in containers via the runner'sdocker://labels.
See docs/architecture.md for the design.
Quickstart
New here? Follow the getting-started walkthrough. The short version:
# build
make build # -> bin/forgejo-autoscaler
# configure
cp configs/example.yaml config.yaml
export FORGEJO_TOKEN=<site-admin-PAT>
# dry-run: exercise the loop against a real Forgejo, no cloud spend
bin/forgejo-autoscaler -config config.yaml -dry-run -log-level debug
Deploy
Run the controller continuously via Docker or systemd:
make docker # build the image
docker compose -f deploy/docker-compose.yml up -d # or run with compose
See docs/deployment.md for the systemd unit, secrets, and Prometheus metrics.
Layout
cmd/forgejo-autoscaler entrypoint (flags, wiring, signals)
internal/config YAML schema, env expansion, defaults, validation
internal/forgejo REST client: waiting jobs, runners, register, delete
internal/provider Provider interface + Scaleway/OVH/Hetzner backends
internal/cloudinit render #cloud-config (Docker + forgejo-runner)
internal/pool scaling decision (pure) + per-pool reconcile
internal/controller reconcile loop + health/metrics server
Docs
- Getting started — clone to a working autoscaler
- Configuration
- Runners and registration
- Deployment
- Architecture
- Features and roadmap
- Providers: Scaleway, OVH, Hetzner
License
MIT. Copyright (c) 2026 Benoit Chesneau bchesneau@pm.me. See LICENSE.