Mirror of benoitc/forgejo-autoscale-runner @ codeberg
  • Go 99.2%
  • Dockerfile 0.4%
  • Makefile 0.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-06-15 13:19:53 +02:00
.forgejo/workflows CI: split into lint/build/test/tidy jobs, add golangci-lint 2026-06-15 11:40:03 +02:00
cmd CI: split into lint/build/test/tidy jobs, add golangci-lint 2026-06-15 11:40:03 +02:00
configs Fix review findings: pool isolation, zone safety, lifecycle 2026-06-15 10:07:16 +02:00
deploy Move to codeberg.org, Forgejo Actions CI, and deployment artifacts 2026-06-14 22:24:24 +02:00
docs Fix review findings: pool isolation, zone safety, lifecycle 2026-06-15 10:07:16 +02:00
internal CI: split into lint/build/test/tidy jobs, add golangci-lint 2026-06-15 11:40:03 +02:00
.dockerignore Move to codeberg.org, Forgejo Actions CI, and deployment artifacts 2026-06-14 22:24:24 +02:00
.gitignore Add provider-probe tool and cloud-init SSH keys 2026-06-14 14:31:18 +02:00
.golangci.yml CI: split into lint/build/test/tidy jobs, add golangci-lint 2026-06-15 11:40:03 +02:00
Dockerfile Move to codeberg.org, Forgejo Actions CI, and deployment artifacts 2026-06-14 22:24:24 +02:00
go.mod Add Hetzner Cloud provider 2026-06-14 22:33:47 +02:00
go.sum Add Hetzner Cloud provider 2026-06-14 22:33:47 +02:00
LICENSE Add MIT license and SPDX copyright headers 2026-06-15 09:18:09 +02:00
Makefile CI: split into lint/build/test/tidy jobs, add golangci-lint 2026-06-15 11:40:03 +02:00
openstack-discover Fix OVH provider for live OVH and add openstack-discover 2026-06-14 21:05:38 +02:00
README.md Add MIT license and SPDX copyright headers 2026-06-15 09:18:09 +02:00

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

  1. Each tick the controller reads instance-wide demand and capacity once:
    • demand: GET /api/v1/admin/actions/runners/jobs, jobs with status: waiting
    • capacity: GET /api/v1/admin/actions/runners, status of idle/active
  2. 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
  3. cloud-init installs Docker and forgejo-runner and starts it. Jobs run in containers via the runner's docker:// 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

License

MIT. Copyright (c) 2026 Benoit Chesneau bchesneau@pm.me. See LICENSE.