Skip to content

Forgejo Runner Forgejo Runner

Build Status Last Commit OCI Pulls

Runs Forgejo Actions jobs natively on FreeBSD, inside the container, for a Forgejo instance.

Registry ghcr.io/daemonless/forgejo-runner
Daemonless daemonless/forgejo-runner
Source code.forgejo.org/forgejo/runner
Website forgejo.org/docs/latest/admin/actions

Registering the runner

In Forgejo, open Site administration > Actions > Runners (or the runners page of an organisation, user or repository), create a runner and copy the UUID and token it shows into FORGEJO_RUNNER_UUID and FORGEJO_RUNNER_TOKEN. On first start the image writes them to /config/config.yaml. After that the file is yours: the variables are not read again while it exists (the container logs a line saying so). Edit the file to change labels, run more than one job at a time (runner.capacity) or let running jobs finish on shutdown (runner.shutdown_timeout; by default podman stop cancels them). Run forgejo-runner generate-config in the container to see every option. Labels must end in :host.

A /config/.runner file left by the old register command conflicts with the generated config: remove it.

Without those variables and without a /config/config.yaml, the container stays up, logs what it needs and starts the runner as soon as the file appears.

What jobs can do

Jobs run inside this container as the bsd user (the runner's host executor). There is no per-job isolation. A job runs as the same user that owns /config, so any workflow can read the runner token in /config/config.yaml, change that file, and leave files behind that later jobs and restarts will see. Only connect this runner to repositories whose workflows, and whose contributors' pull requests, you trust. Select it in a workflow with runs-on: freebsd.

The image ships git, node (for JavaScript actions such as actions/checkout) and bash. Anything else a job needs has to be added in an image built from this one. Workflows written for Linux containers (container:, services:, Docker actions) do not run on this executor.

Prerequisites

Before deploying, ensure your host environment is ready. See the Quick Start Guide for host setup instructions, including the security model for host vs. container privileges.

Deployment

Customize Paths, UID & Ports

Install and manage Forgejo Runner on FreeBSD with fjord:

fjord install forgejo-runner

Or open the App Store in the fjord web UI and install Forgejo Runner from the wizard. New to fjord? See the Install Guide.

services:
  forgejo-runner:
    image: "ghcr.io/daemonless/forgejo-runner:latest"
    container_name: forgejo-runner
    environment:
      - PUID=1000  # User ID for the runner and the jobs it runs
      - PGID=1000  # Group ID for the runner and the jobs it runs
      - TZ=UTC  # Timezone for the container
      - FORGEJO_URL=  # URL of the Forgejo instance, as the runner reaches it (e.g. https://git.example.com)
      - FORGEJO_RUNNER_UUID=  # UUID Forgejo shows when you create the runner
      - FORGEJO_RUNNER_TOKEN=<FORGEJO_RUNNER_TOKEN>  # Token Forgejo shows when you create the runner
    volumes:
      - "/containers/forgejo-runner:/config"
    # always (not unless-stopped) so FreeBSD's podman rc.d auto-starts it at boot
    restart: always

Save as compose.yaml, then run podman-compose up -d.

1
2
3
4
5
6
7
8
9
# .env

DIRECTOR_PROJECT=forgejo-runner
PUID=1000
PGID=1000
TZ=UTC
FORGEJO_URL=
FORGEJO_RUNNER_UUID=
FORGEJO_RUNNER_TOKEN=<FORGEJO_RUNNER_TOKEN>
# appjail-director.yml

options:
  - virtualnet: ':<random> default'
  - nat:
services:
  forgejo-runner:
    name: forgejo_runner
    options:
      - container: 'args:--pull'
    oci:
      user: root
      environment:
        - PUID: !ENV '${PUID}'
        - PGID: !ENV '${PGID}'
        - TZ: !ENV '${TZ}'
        - FORGEJO_URL: !ENV '${FORGEJO_URL}'
        - FORGEJO_RUNNER_UUID: !ENV '${FORGEJO_RUNNER_UUID}'
        - FORGEJO_RUNNER_TOKEN: !ENV '${FORGEJO_RUNNER_TOKEN}'
    volumes:
      - forgejo-runner: /config
volumes:
  forgejo-runner:
    device: '/containers/forgejo-runner'
1
2
3
4
5
6
7
# Makejail

ARG tag=latest

OPTION container=boot
OPTION overwrite=force
OPTION from=ghcr.io/daemonless/forgejo-runner:${tag}

Save the files above, then run appjail-director up.

Experimental

Bastille's OCI support is experimental. It requires buildah and shares the host network stack (inherit). Mount volumes with --volume HOST JAIL; without it, image-declared volumes are stored under ${bastille_volumesdir}/${jail}.

services:
  forgejo-runner:
    name: forgejo-runner
    image: "ghcr.io/daemonless/forgejo-runner:latest"
    network:
      - mode: host
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
      - FORGEJO_URL=
      - FORGEJO_RUNNER_UUID=
      - FORGEJO_RUNNER_TOKEN=<FORGEJO_RUNNER_TOKEN>
    volumes:
      - "/containers/forgejo-runner:/config"

Save as bastille-compose.yml, then run bastille up.

Parameters

Environment Variables

Variable Default Description
PUID 1000 User ID for the runner and the jobs it runs
PGID 1000 Group ID for the runner and the jobs it runs
TZ UTC Timezone for the container
FORGEJO_URL `` URL of the Forgejo instance, as the runner reaches it (e.g. https://git.example.com)
FORGEJO_RUNNER_UUID `` UUID Forgejo shows when you create the runner
FORGEJO_RUNNER_TOKEN <FORGEJO_RUNNER_TOKEN> Token Forgejo shows when you create the runner

Volumes

Path Description
/config config.yaml (holds the runner token), action cache and job workspaces

Version Tags

Multi-arch manifests — resolve automatically to the right image for your platform.

Tag Description Best For
latest / pkg Upstream Binary. Built from official release. Most users — recommended.
pkg-latest FreeBSD Latest. Rolling package updates. Staying current.
Tag Description Best For
latest-amd64 / pkg-amd64 Upstream Binary. Built from official release. Most users — recommended.
pkg-latest-amd64 FreeBSD Latest. Rolling package updates. Staying current.
Tag Description Best For
latest-aarch64 / pkg-aarch64 Upstream Binary. Built from official release. Most users — recommended.
pkg-latest-aarch64 FreeBSD Latest. Rolling package updates. Staying current.

Implementation Details

  • Architectures: amd64, aarch64
  • User: bsd (UID/GID set via PUID/PGID). Defaults to 1000:1000.
  • Base: Built on ghcr.io/daemonless/base (FreeBSD 15.1).

Need help? Join our Discord community.