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

Forgejo Runner is the CI/CD runner that executes Forgejo Actions workflows. When you push to a repository on a Forgejo instance and a workflow triggers, it is a registered runner that actually picks up the jobs and runs them, whether inside Docker containers or directly on the host.

The workflow syntax is compatible with GitHub Actions, so much of the wider Actions ecosystem works unchanged. What you supply is the compute: one or more runners, registered against your forge, ready to execute jobs on labels you define.

Forgejo Runner is not in the official Debian repositories, and it needs to stay roughly in step with your Forgejo release. The unofficial deb.griffo.io repository provides an up-to-date, prebuilt forgejo-runner package that installs and updates cleanly with apt, so you are not chasing release binaries by hand.

Install the Latest Forgejo Runner on Debian: The Short Version

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

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 defined in your repositories’ .forgejo/workflows
  • 🐳 Docker and host execution - Run jobs in isolated containers or natively on the machine
  • 🏷️ Label-based routing - Direct jobs to specific runners using labels you choose
  • 🔁 GitHub Actions compatibility - Reuses much of the existing Actions ecosystem
  • ⚙️ Simple registration - One command links a runner to a forge with a token
  • 📄 Declarative config - A single config.yml controls capacity, caching and labels
  • 🪶 Single Go binary - No heavy runtime; just the binary and optionally Docker
  • 🔀 Scales horizontally - Add more runners to increase build throughput

Why Use the deb.griffo.io Repository?

  • Easy installation and updates through the APT package manager
  • Automatic dependency management handled by Debian packaging
  • Always tracks upstream releases so the runner stays compatible with your forge
  • No compiling from source and no manual binary downloads
  • Works across supported Debian releases (Bookworm, Trixie and Sid)

Prerequisites

Before you begin, make sure you have:

  • A Debian-based system (Bookworm 12, Trixie 13, or Sid)
  • sudo privileges
  • curl installed (sudo apt install curl if needed)
  • A running Forgejo instance you can 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

Add the signing key and the repository to 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

What each command does:

  1. Keyrings directory - Creates /etc/apt/keyrings with correct permissions.
  2. GPG key - Downloads and de-armours the key so APT can verify signatures.
  3. Repository entry - Registers the source pinned to the key, with your codename supplied by lsb_release -sc.
  4. Update - Refreshes the package index.

Step 2: Update the Package List

If you skipped the last line above, run:

sudo apt update

Step 3: Install Forgejo Runner

Install the package:

sudo apt install forgejo-runner

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

Step 4: Verify the Installation

Confirm the binary and its version:

forgejo-runner --version

You should see output similar to:

forgejo-runner version v6.3.1

Getting Started with Forgejo Runner

A freshly installed runner does nothing until it is registered against a forge and started. Below is the typical bring-up.

Obtain a Registration Token

Log in to your Forgejo instance and generate a runner registration token. The scope determines what the runner can pick up:

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

Copy the token shown; you will pass it to the register command.

Register the Runner

Registration links the binary to your forge and writes a .runner file holding the credentials. You can register non-interactively:

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

The --labels flag defines which job runners this instance will accept. Here, jobs requesting docker run inside the node:20-bookworm image, while jobs requesting native run directly on the host.

Generate a Config File

For anything beyond defaults, generate a config.yml and edit it:

forgejo-runner generate-config > config.yml

The file lets you tune concurrency (runner.capacity), the cache server, network settings, and container options. For example, raise capacity to run several jobs in parallel:

runner:
  capacity: 4
  timeout: 3h

Run the Daemon

Start the runner so it begins polling the forge for jobs:

forgejo-runner daemon --config config.yml

You should see it connect and report as online in the forge’s runners list. Leave this process running; a queued workflow will now be picked up and executed.

Run It as a systemd Service

For a persistent setup, run the daemon under systemd so it survives reboots. 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

Then enable and start it:

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

Make sure the .runner credentials file lives in the working directory so the daemon can find it.

Keeping Forgejo Runner Updated

Upgrades come with your normal package maintenance:

sudo apt update && sudo apt upgrade

Restart the runner after an upgrade so the new binary takes effect. Keep the runner reasonably close to your Forgejo version to avoid compatibility surprises.

Other Tools from deb.griffo.io

The repository packages other self-hosting and developer tooling that complements a CI setup:

  • 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-add the signing 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 find the forgejo-runner package:

  1. Run sudo apt update again to refresh the index.
  2. Confirm your release is supported (Bookworm, Trixie, or Sid).
  3. Check the source entry: cat /etc/apt/sources.list.d/deb.griffo.io.list

Runner Registers but Jobs Never Run

If the runner shows online but workflows stay queued, the usual cause is a label mismatch: the labels your workflow requests (runs-on:) do not match any label the runner registered. Confirm the labels with:

cat .runner

Also make sure Actions is enabled for the repository and, for Docker labels, that the runner user can talk to 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

The .runner credentials 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 the piece that turns a Forgejo instance into a full CI/CD platform. Installing it from deb.griffo.io gives you a maintained binary that upgrades with the rest of your system, so it stays aligned with your forge instead of drifting.

Grab a registration token, register with the labels you want, run the daemon under systemd, and your Forgejo Actions workflows have compute to run on.

Frequently Asked Questions

How do I install the latest Forgejo Runner on Debian?

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 Debian. 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 Ubuntu?

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

Which Debian releases are supported?

Bookworm 12, Trixie 13 and Sid. 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.