# ![Forgejo Runner](<https://daemonless.io/images/logos/forgejo-runner.svg>) Forgejo Runner

[![Build Status](<https://img.shields.io/github/actions/workflow/status/daemonless/forgejo-runner/build.yaml?style=flat-square&amp;label=Build&amp;color=green>)](<https://github.com/daemonless/forgejo-runner/actions>) [![Last Commit](<https://img.shields.io/github/last-commit/daemonless/forgejo-runner?style=flat-square&amp;label=Last+Commit&amp;color=blue>)](<https://github.com/daemonless/forgejo-runner/commits>) [![OCI Pulls](<https://img.shields.io/docker/pulls/daemonless/forgejo-runner?style=flat-square&amp;label=OCI+Pulls&amp;color=blue>)](<https://hub.docker.com/r/daemonless/forgejo-runner>)

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

|  |  |
| --- | --- |
| **Registry** | [`ghcr.io/daemonless/forgejo-runner`](<https://github.com/daemonless/forgejo-runner/pkgs/container/forgejo-runner>) |
| **Daemonless** | [daemonless/forgejo-runner](<https://github.com/daemonless/forgejo-runner>) |
| **Source** | [code.forgejo.org/forgejo/runner](<https://code.forgejo.org/forgejo/runner>) |
| **Website** | [forgejo.org/docs/latest/admin/actions](<https://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](<https://daemonless.io/guides/quick-start/index.md>) for host setup instructions, including the security model for host vs. container privileges.

## Deployment

**Customize Paths, UID &amp; Ports**

Install and manage **Forgejo Runner** on FreeBSD with [fjord](<https://fjord.daemonless.io>):

```
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](<https://fjord.daemonless.io/install/>).

```
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`.

```
# .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'
```

```
# 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`.

> [!WARNING]
>
> **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](<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. |

> [!NOTE]
>
> **Implementation Details**
>
> - **Architectures:** amd64, aarch64
> - **User:** `bsd` (UID/GID set via [PUID/PGID](<https://daemonless.io/guides/permissions/index.md>)). Defaults to `1000:1000`.
> - **Base:** Built on `ghcr.io/daemonless/base` (FreeBSD 15.1).

---

Need help? Join our [Discord](<https://discord.gg/Kb9tkhecZT>) community.
