Forgejo Runner
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:
Or open the App Store in the fjord web UI and install Forgejo Runner from the wizard. New to fjord? See the Install Guide.
Save as compose.yaml, then run podman-compose up -d.
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}.
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 to1000:1000. - Base: Built on
ghcr.io/daemonless/base(FreeBSD 15.1).
Need help? Join our Discord community.