How to Install Forgejo Runner on Ubuntu: The CI/CD Runner for Forgejo Actions

Forgejo Runner is the CI/CD runner that executes Forgejo Actions workflows. Whenever a push or another event triggers a workflow on your Forgejo instance, a registered runner is what claims the job and runs it, either inside a Docker container or straight on the host machine.

Because the workflow syntax is compatible with GitHub Actions, a large slice of the existing Actions ecosystem works without modification. Your job is to provide the compute: one or more runners, registered to the forge and configured with the labels your workflows target.

Ubuntu does not carry Forgejo Runner in its default archives, and it should track your Forgejo release reasonably closely. The unofficial deb.griffo.io repository provides an up-to-date, prebuilt forgejo-runner package that installs and upgrades with apt, sparing you the manual binary chase.

Install the Latest Forgejo Runner on Ubuntu: The Short Version

If you only came for the commands, this adds the repository and installs the latest Forgejo Runner .deb package on Ubuntu:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
sudo apt update
sudo apt install forgejo-runner

The rest of this guide explains what each command does, how to verify the install, how to keep Forgejo Runner up to date, and what to check when something goes wrong.

What Makes Forgejo Runner Special?

  • 🎬 Forgejo Actions execution - Runs the workflows in your repositories’ .forgejo/workflows
  • 🐳 Docker and host execution - Isolated container jobs or native host jobs, your choice
  • 🏷️ Label-based routing - Send jobs to the right runner using labels you define
  • 🔁 GitHub Actions compatibility - Reuse much of the existing Actions ecosystem
  • ⚙️ Simple registration - A single command connects a runner to a forge via a token
  • 📄 Declarative config - One config.yml governs capacity, caching and labels
  • 🪶 Single Go binary - Lightweight; just the binary plus optionally Docker
  • 🔀 Scales horizontally - Add runners to grow build throughput

Why Use the deb.griffo.io Repository?

  • Easy installation and updates through the APT package manager
  • Automatic dependency management handled by Debian/Ubuntu packaging
  • Always tracks upstream releases so the runner stays compatible with your forge
  • No compiling from source and no manual downloads
  • Works across supported Ubuntu releases with the codename detected automatically

Prerequisites

Before you begin, make sure you have:

  • An Ubuntu system (Jammy 22.04 LTS, Noble 24.04 LTS, or newer)
  • sudo privileges
  • curl installed (sudo apt install curl if needed)
  • A running Forgejo instance you administer (see the Forgejo install guide)
  • Docker installed if you plan to run jobs in containers (sudo apt install docker.io)

Step 1: Add the deb.griffo.io Repository

Register the signing key and repository with APT:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

The commands, explained:

  1. Keyrings directory - Ensures /etc/apt/keyrings exists with the right permissions.
  2. GPG key - Fetches and de-armours the key for signature verification.
  3. Repository entry - Adds the source pinned to the key, with lsb_release -sc inserting your Ubuntu codename.
  4. Update - Refreshes the package index.

Step 2: Update the Package List

Run this if you did not already:

sudo apt update

Step 3: Install Forgejo Runner

Install the package:

sudo apt install forgejo-runner

APT pulls in dependencies and places the forgejo-runner binary on your PATH.

Step 4: Verify the Installation

Check the version:

forgejo-runner --version

Expected output looks like:

forgejo-runner version v6.3.1

Getting Started with Forgejo Runner

A newly installed runner is idle until you register it with a forge and start the daemon. Here is the standard sequence.

Obtain a Registration Token

In your Forgejo instance, generate a runner registration token at the scope you want the runner to serve:

  • Repository: the repository’s Settings → Actions → Runners
  • Organisation: the organisation’s Settings → Actions → Runners
  • Site-wide: Site Administration → Actions → Runners → “Create new Runner”

Copy the displayed token for the next step.

Register the Runner

Registration ties the binary to your forge and writes a .runner credentials file. A non-interactive registration looks like this:

forgejo-runner register \
  --no-interactive \
  --instance https://forge.example.com \
  --token <REGISTRATION_TOKEN> \
  --name ubuntu-runner-01 \
  --labels docker:docker://node:20-bookworm,native:host

The --labels list decides which jobs this runner accepts. In this example, docker jobs run inside the node:20-bookworm image and native jobs run directly on the host.

Generate a Config File

Create a config.yml when you need more control than the defaults offer:

forgejo-runner generate-config > config.yml

Edit it to set concurrency, caching and container behaviour. For instance, to run four jobs at once:

runner:
  capacity: 4
  timeout: 3h

Run the Daemon

Start the runner so it begins polling for jobs:

forgejo-runner daemon --config config.yml

It should connect and appear as online in the forge’s runners list, after which queued workflows are picked up and executed.

Run It as a systemd Service

For a durable setup, run the daemon under systemd. Create /etc/systemd/system/forgejo-runner.service:

[Unit]
Description=Forgejo Runner
After=network.target docker.service

[Service]
ExecStart=/usr/bin/forgejo-runner daemon --config /etc/forgejo-runner/config.yml
WorkingDirectory=/var/lib/forgejo-runner
User=forgejo-runner
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now forgejo-runner

Keep the .runner file in the working directory so the daemon can read its credentials.

Keeping Forgejo Runner Updated

Upgrades arrive through routine package maintenance:

sudo apt update && sudo apt upgrade

Restart the runner after upgrading so the new binary loads. Keeping the runner close to your Forgejo version avoids compatibility issues.

Other Tools from deb.griffo.io

The repository packages other self-hosting and developer tooling that pairs well with CI:

  • Forgejo - The self-hosted Git forge the runner connects to
  • Lazygit - A fast terminal UI for everyday Git operations
  • just - A handy command runner for project-specific tasks
  • k9s - A terminal UI for managing Kubernetes clusters

Troubleshooting

GPG or Key Errors

If APT cannot verify the repository, re-import the key:

sudo rm -f /etc/apt/keyrings/deb.griffo.io.gpg
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If APT cannot locate the forgejo-runner package:

  1. Run sudo apt update to refresh the index.
  2. Confirm you are on a supported release (Jammy 22.04, Noble 24.04, or newer).
  3. Inspect the source entry: cat /etc/apt/sources.list.d/deb.griffo.io.list

Runner Registers but Jobs Never Run

If the runner is online yet workflows stay queued, it is almost always a label mismatch: the runs-on: label in the workflow does not match any label the runner registered. Check the registered labels with:

cat .runner

Also confirm Actions is enabled for the repository, and for Docker labels ensure the runner user can reach the Docker socket (sudo usermod -aG docker forgejo-runner).

Uninstalling

To remove Forgejo Runner:

sudo systemctl disable --now forgejo-runner
sudo apt remove forgejo-runner

Your .runner file and any config.yml remain until you delete them. To remove the repository:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Conclusion

Forgejo Runner is what makes a Forgejo instance a complete CI/CD platform. Installing it from deb.griffo.io gives you a maintained binary that upgrades with the rest of your Ubuntu system, keeping it aligned with your forge.

Fetch a registration token, register with the labels you need, run the daemon under systemd, and your Forgejo Actions workflows have somewhere to run.

Frequently Asked Questions

How do I install the latest Forgejo Runner on Ubuntu?

Add the deb.griffo.io APT repository and its signing key, then run sudo apt install forgejo-runner. The repository tracks upstream Forgejo Runner releases, so you get the latest packaged version rather than a build frozen when your distribution was released.

Is there a .deb package for Forgejo Runner?

Yes. deb.griffo.io publishes Forgejo Runner as a signed .deb for Ubuntu. You could download that .deb and install it by hand, but adding the repository is the better option: APT then resolves dependencies and picks up new versions on its own.

How do I update Forgejo Runner to the latest version?

Run sudo apt update && sudo apt upgrade. Once Forgejo Runner is installed from APT there is no separate updater to remember, since new releases arrive with the rest of your system updates.

How do I install Forgejo Runner on Debian?

Exactly the same way; lsb_release -sc simply resolves to a different codename. There is a companion guide with the Debian specifics: How to install Forgejo Runner on Debian.

Which Ubuntu releases are supported?

Jammy 22.04 LTS, Noble 24.04 LTS and newer. Because the repository line is built from lsb_release -sc, the matching suite is selected for you.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream Forgejo project.