Forgejo KEDA Adapter

forgejo-keda-adapter is a small Go service that converts Forgejo runner jobs into a single numeric metric for KEDA's metrics-api scaler.

It polls Forgejo's runner jobs API and exposes a KEDA-friendly response:

{"value":7,"jobs_total":7,"counted_statuses":["running","waiting"]}

The intended module and source location is:

code.carverauto.dev/carverauto/forgejo-keda-adapter

Why This Exists

Forgejo exposes runner jobs as a JSON list, not as a scalar metric. KEDA only needs a number. This adapter is the shim between those two shapes.

The pattern is:

1. Query Forgejo for runner jobs.
2. Count jobs in the statuses you care about.
3. Return {"value": N} over HTTP.
4. Point a KEDA metrics-api trigger at that endpoint.

No Prometheus exporter or Kubernetes custom metrics adapter is required.

Endpoints

• GET /jobs
• GET /healthz

Configuration

• FORGEJO_JOBS_URL: required
• FORGEJO_API_TOKEN: required
• FORGEJO_COUNT_STATUSES: default waiting,running
• FORGEJO_TIMEOUT_SECONDS: default 3
• PORT: default 8080

If you only want queued jobs, set:

export FORGEJO_COUNT_STATUSES=waiting

Forgejo API Notes

This was proven against:

/api/v1/admin/runners/jobs

On our Forgejo build, the filtered form with ?labels=... returned null even when jobs existed. The unfiltered admin endpoint returned the correct list, so the working production setup polls the unfiltered admin jobs API.

That means this setup currently works best for a single runner pool. If you run multiple independent pools, you may need stronger server-side filtering than Forgejo currently provides.

Local Run

go run ./cmd/forgejo-keda-adapter

With env:

export FORGEJO_JOBS_URL='https://forgejo.example.com/api/v1/admin/runners/jobs'
export FORGEJO_API_TOKEN='replace-me'
export FORGEJO_COUNT_STATUSES='waiting,running'

Then:

curl http://127.0.0.1:8080/jobs
curl http://127.0.0.1:8080/healthz

Tests

go test ./...

Container Build

docker build -t forgejo-keda-adapter:dev .
docker run --rm -p 8080:8080 \
  -e FORGEJO_JOBS_URL='https://forgejo.example.com/api/v1/admin/runners/jobs' \
  -e FORGEJO_API_TOKEN='replace-me' \
  forgejo-keda-adapter:dev

Kubernetes Example

Example manifests live under examples/kubernetes:

• deployment.yaml
• service.yaml
• scaledobject.yaml

The example ScaledObject targets one counted job per runner pod with delayed scale-down:

• pollingInterval: 15
• cooldownPeriod: 300
• stabilizationWindowSeconds: 300
• targetValue: 1

CI And Release Automation

This repo now includes Forgejo Actions workflows under .forgejo/workflows:

• ci.yml: runs go test ./..., builds the binary, and verifies docker build
• release.yml: on v* tags, builds a linux/amd64 release tarball, pushes the linux/amd64 container image to registry.carverauto.dev/serviceradar/forgejo-keda-adapter, and creates or updates a Forgejo release

Required secrets:

• HARBOR_ROBOT_USERNAME
• HARBOR_ROBOT_SECRET
• FORGEJO_TOKEN

License

This project is licensed under MIT. See LICENSE.