A managed Forgejo runner for builds that need more machine

A Forgejo runner is the program that executes your Forgejo Actions jobs. Forgejo schedules jobs from .forgejo/workflows/ and never runs them itself, so every instance needs at least one runner. For a linter or a small test suite, a spare VM does the job. A C++ codebase, a Rust workspace or an Android app with a long Gradle build needs a bigger machine, and someone has to keep it patched and clean.

Status: Forgejo Actions is on the cirunner.dev roadmap. Our early access starts with GitHub Actions and GitLab CI. This page describes how Forgejo support will work.

Where Forgejo CI runners run out of room

Self-hosted Forgejo has no hosted runner tier. You bring the hardware. On Codeberg you get small hosted runners with short time limits, intended for public free-software projects (see the Codeberg page). Compile-heavy teams hit the same walls on both:

• The one shared runner VM queues jobs during the morning rush and idles at night.
• Builds that scale with cores wait on a machine sized for the average job.
• arm64 builds or GPU tests need a second machine that sits idle most days and still needs maintenance.
• Long-lived runners collect Docker images, caches and leftover state from earlier jobs until the disk fills.

What running your own Forgejo Actions runner involves

The Forgejo runner setup guide walks through it in detail. In short:

• Install forgejo-runner (the 13.x line is current), create an unprivileged user and generate a config file.
• Create the runner in the Forgejo UI under Create new runner and paste the UUID and token into server.connections. The older forgejo-runner register command is deprecated.
• Pick labels that map to Docker, Podman, LXC or the bare host, and keep privileged mode off.
• For isolation, register ephemeral runners that take one job each. Forgejo does not autoscale runners; the on-demand example in the runner repository is a Bash loop with open problems listed in its README.

After that comes the upkeep: OS patches, runner upgrades, disk cleanup and a plan for the job that holds a slot for the full three-hour default timeout.

How a custom Forgejo runner from cirunner.dev will work

You keep your Forgejo instance and your workflow files. We run the machines.

1. You create a runner registration for the scope you want (repository, organization, user or instance) and give us the credentials Forgejo shows, or an API token that lets us create one-job runners for waiting jobs.
2. You pick a machine shape in the configurator: more cores and memory than a typical runner VM, x86 or ARM, a GPU if you need one.
3. Your workflow targets the runner with a label you choose, for example runs-on: big-arm64.
4. Each job gets a fresh VM that we destroy when the job ends. A build cache persists between jobs so the next build does not start cold.

Billing is usage-based, per compute minute. Your Forgejo server only needs to accept outbound connections from the runner, the same as with a runner you host.

Forgejo runner options compared

Who a managed Forgejo runner fits

Good fit:

• Teams on self-hosted Forgejo with C, C++, Rust, game engine or embedded builds that take tens of minutes.
• Projects that need arm64 or GPU jobs next to their amd64 jobs.
• Small teams with no one who wants to own a runner fleet.

Poor fit:

• A static site or a small web app whose pipeline finishes in two minutes. One cheap runner VM covers that.
• Builds that must reach machines on a network you cannot expose to an outside runner.

FAQ

Is there a managed Forgejo runner?

Forgejo itself ships none, and Codeberg's hosted runners are limited to public free-software projects. cirunner.dev has a managed Forgejo runner on its roadmap. It does not run Forgejo jobs yet; you can vote for it on the early-access form.

Can I use a custom Forgejo runner with Codeberg?

Yes. Codeberg lets you attach your own Forgejo runner to a repository, user or organization through Create new runner. Offline registration with forgejo-cli does not work there because it needs admin access to the server.

Does the Forgejo Actions runner work with Gitea?

No. Gitea has its own runner, renamed from act_runner to Gitea Runner. See the Gitea runner page.

How do I autoscale Forgejo CI runners?

Forgejo has no built-in autoscaler. You register ephemeral runners through forgejo-cli or the API and run forgejo-runner one-job on machines that your own script creates and deletes. The setup guide covers the details and the known gaps.