Setting Up a Forgejo Actions Runner

Push-to-deploy with a self-hosted Forgejo Actions runner on the same VPS: own user, no Docker, narrow sudo rights and secrets kept in Forgejo.

Article Created Updated Also in German: Forgejo Actions Runner einrichten

Reviewed by adrian on

After moving my Git repositories from GitHub to a self-hosted Forgejo instance, the next step was to move deployment off my laptop. Instead of running ./scripts/deploy.sh locally and hoping nothing was uncommitted, I wanted git push to trigger the build and roll out the container automatically.

The setup

  • VPS: a single Debian machine hosting both Forgejo (rootless Podman container) and the website (/opt/websites/adrian-altner.de, run by a podman-compose@ systemd service).
  • Forgejo: v11 LTS, rootless, running under a dedicated git system user.
  • Goal: on every push to main, rebuild the production image and restart the service, all on the same machine.

Why a dedicated runner user

The runner executes whatever code the workflow files define. Running it as the git user, which has access to Forgejo's database and every repository, would be a bad idea. I created a separate system user with its own home directory:

sudo useradd --system --create-home \
  --home-dir /var/lib/forgejo-runner \
  --shell /bin/bash forgejo-runner

That user gets no sudo by default. Further down, it gets targeted rights for exactly the commands the deploy needs.

Install the runner binary

The runner comes as a single static binary from Forgejo's own registry. I fetched the latest release with a script:

LATEST=$(curl -s https://code.forgejo.org/api/v1/repos/forgejo/runner/releases \
  | grep -oE '"tag_name":"v[0-9.]+"' | head -1 | cut -d'"' -f4)
VER="${LATEST#v}"

cd /tmp
curl -L -o forgejo-runner \
  "https://code.forgejo.org/forgejo/runner/releases/download/${LATEST}/forgejo-runner-${VER}-linux-amd64"
chmod +x forgejo-runner
sudo mv forgejo-runner /usr/local/bin/

forgejo-runner --version confirmed v12.9.0, the current major version, compatible with Forgejo v10, v11 and later.

Enable Actions in Forgejo

Actions are off by default. I added the minimal configuration to app.ini (inside the rootless container's volume at /home/git/forgejo-data/custom/conf/app.ini):

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://code.forgejo.org

DEFAULT_ACTIONS_URL matters because GitHub's Actions marketplace isn't reachable as it is. Forgejo keeps its own mirrors of common actions such as actions/checkout at code.forgejo.org/actions/*. After a container restart, the actions_artifacts storage directory showed up in the logs.

Register the runner

A runner can serve a single repository, a user account or the whole instance. I started with a registration for my website's repository, then moved it to my user account, so the same runner serves every repository I own without registering again.

The registration token comes from User Settings → Actions → Runners → Create new Runner:

sudo -iu forgejo-runner /usr/local/bin/forgejo-runner register \
  --no-interactive \
  --instance https://git.altner.cloud \
  --token <REGISTRATION_TOKEN> \
  --name arcturus-runner \
  --labels "self-hosted:host"

The label self-hosted:host means "jobs labelled self-hosted run directly on the host". The runner itself needs no container runtime; Podman is already there for the application.

To move an existing runner from a repository to the user account, stop the service. Then delete the old runner in the Forgejo interface, remove /var/lib/forgejo-runner/.runner locally, get a new user-level token, register again, start the service. Same binary, different scope.

Running without Docker

On first start, the runner refused to run:

Error: daemon Docker Engine socket not found and docker_host config was invalid

Even with only the host label, the runner looks for a Docker socket on startup. The server only has rootless Podman, so I generated a config file and switched the Docker check off:

sudo -iu forgejo-runner /usr/local/bin/forgejo-runner generate-config \
  > /tmp/runner-config.yaml
sudo mv /tmp/runner-config.yaml /var/lib/forgejo-runner/config.yaml
sudo chown forgejo-runner:forgejo-runner /var/lib/forgejo-runner/config.yaml

sudo -iu forgejo-runner sed -i \
  -e 's|docker_host: .*|docker_host: "-"|' \
  -e 's|  labels: \[\]|  labels: ["self-hosted:host"]|' \
  /var/lib/forgejo-runner/config.yaml

Systemd service

[Unit]
Description=Forgejo Actions Runner
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=forgejo-runner
Group=forgejo-runner
WorkingDirectory=/var/lib/forgejo-runner
ExecStart=/usr/local/bin/forgejo-runner --config /var/lib/forgejo-runner/config.yaml daemon
Restart=on-failure
RestartSec=5s
NoNewPrivileges=false
ProtectSystem=full
ProtectHome=read-only
ReadWritePaths=/var/lib/forgejo-runner

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now forgejo-runner

Just enough sudo

The deploy step builds a Podman image and restarts the systemd service that runs it. Both need root. Instead of giving the runner user broad sudo, I wrote a narrow allowlist in /etc/sudoers.d/forgejo-runner-deploy:

forgejo-runner ALL=(root) NOPASSWD: /usr/bin/podman build *, \
                                    /usr/bin/podman container prune *, \
                                    /usr/bin/podman image prune *, \
                                    /usr/bin/podman builder prune *, \
                                    /usr/bin/systemctl restart [email protected], \
                                    /usr/bin/rsync *

visudo -cf checks the syntax before you lock yourself out of sudo entirely.

The workflow

Workflows live under .forgejo/workflows/*.yml. The deploy does what my old shell script did, minus the SSH:

name: Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: self-hosted
    env:
      DEPLOY_DIR: /opt/websites/adrian-altner.de
    steps:
      - uses: actions/checkout@v4

      - name: Sync to deploy directory
        run: |
          sudo rsync -a --delete \
            --exclude='.env' \
            --exclude='.env.production' \
            --exclude='.git/' \
            --exclude='node_modules/' \
            ./ "${DEPLOY_DIR}/"

      - name: Build image
        run: |
          cd "${DEPLOY_DIR}"
          sudo podman build \
            --build-arg WEBMENTION_TOKEN="${{ secrets.WEBMENTION_TOKEN }}" \
            -t localhost/adrian-altner.de:latest .

      - name: Restart service
        run: sudo systemctl restart [email protected]

      - name: Prune
        run: |
          sudo podman container prune -f 2>/dev/null || true
          sudo podman image prune --external -f 2>/dev/null || true
          sudo podman image prune -f 2>/dev/null || true
          sudo podman builder prune -af 2>/dev/null || true

Secrets stay in Forgejo

Anything sensitive, in my case the API tokens for webmention.io and webmention.app, lives in Settings → Actions → Secrets and reaches the job as ${{ secrets.NAME }}. Forgejo stores secrets encrypted, and the workflow logs mask their values. The tokens appear in exactly two places: the workflow file (committed, by name only) and Forgejo's encrypted store (never in the repository).

The build-time token goes into the container as an ARG, is used only during the build stage and isn't present in the final image. podman run --rm <image> env | grep -i webmention confirms it's gone.

The one gotcha: Node on the host

The first real workflow run failed straight away:

Cannot find: node in PATH

actions/checkout@v4 is a JavaScript action. On a runner with the host label it runs directly on the VPS and needs a Node interpreter in PATH. One apt install later the runner was happy:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo systemctl restart forgejo-runner

Result

From git push origin main to the end of the pipeline (checkout, rsync, Podman build, systemd restart, prune, Webmention pings) takes about 1 minute 15 seconds. No SSH keys to rotate, no laptop involved, no doubt about which version of the code is live.

The runner uses about 5 MB of RAM while idle and asks Forgejo for new jobs every two seconds.

Reusing the runner for new projects

Because the runner is registered for my user account, CI for a new repository takes three steps:

  1. Add a .forgejo/workflows/deploy.yml with runs-on: self-hosted to the repository.
  2. Add the project's secrets in the repository's Actions settings.
  3. If the project has its own systemd service, add a line for systemctl restart <new-service> to /etc/sudoers.d/forgejo-runner-deploy. Nothing else on the server changes.

The one-time work (user account, binary, config, systemd unit, Node, sudoers) pays off with every further project.

Based on

  • Setting up a Forgejo Actions runner for self-hosted CI/CD (raw/2026/2026-04-22/setting-up-a-forgejo-actions-runner-for-self-hosted-ci-cd.md) [post]

More on this

Topic

  • Self-Hosting Running services on a server you control instead of using a provider's hosted version, with the upkeep that comes with it.

Builds on

Uses

  • Forgejo Git forge to host yourself: repositories, users, SSH access and CI/CD with Forgejo Actions and self-hosted runners. Codeberg runs on it.
  • Podman Container engine without a background daemon that runs rootless by default on Linux and uses the same commands on macOS and on a server.

Mentioned in

Show in the graph view