Forgejo Actions Images

This repository builds two base images for Forgejo Actions jobs:

ubuntu-26.04
debian-sid

They follow the same idea as catthehacker/ubuntu:act-*: start from a minimal distro image, install the tools most Actions expect, and run jobs as a non-root runner user with passwordless sudo.

Both images also create a writable GitHub-style toolcache at /opt/hostedtoolcache and set RUNNER_TOOL_CACHE, AGENT_TOOLSDIRECTORY, and RUNNER_TEMP so actions that expect hosted-runner paths (such as docker/setup-buildx-action) work under the non-root runner user.

Build locally

docker build -t forgejo-actions-ubuntu:26.04 .
docker build -f Dockerfile.debian-sid -t forgejo-actions-debian:sid .

Ubuntu package installs default to the https://pkgs.ofkm.us/ubuntu cache mirror during the image build. Override it with --build-arg APT_MIRROR=... if needed. Debian Sid package installs default to https://pkgs.ofkm.us/debian with https://pkgs.ofkm.us/debian-security for Debian security sources when present. Override them with --build-arg APT_MIRROR=... and --build-arg APT_SECURITY_MIRROR=... if your cache layout differs.

The build bootstraps ca-certificates from the default Ubuntu sources first, then rewrites apt to the cache mirror before installing the rest of the packages. That avoids HTTPS certificate validation failures in the minimal base image. The Debian Sid build uses the same CA bootstrap pattern before rewriting apt to the Debian cache mirrors.

Use with Forgejo Actions

Point your runner label at the image in the Forgejo runner config:

container:
  labels:
    ubuntu-26.04: docker://forgejo-actions-ubuntu:26.04
    debian-sid: docker://forgejo-actions-debian:sid

Then workflows can use:

jobs:
  test:
    runs-on: ubuntu-26.04
    steps:
      - uses: actions/checkout@v4
      - run: node --version
      - run: docker --version

Or use Debian Sid:

jobs:
  test:
    runs-on: debian-sid
    steps:
      - uses: actions/checkout@v4
      - run: node --version
      - run: docker --version

Customize it

Edit scripts/install.sh or scripts/install-debian.sh to add or remove packages. Keep general command-line tools in the main apt-get install block so the images remain easy to audit.

Use Docker build args when you only need to change versions or the runner user:

docker build \
  --build-arg APT_MIRROR=https://pkgs.ofkm.us/ubuntu \
  --build-arg NODE_MAJOR=24 \
  --build-arg RUNNER_USER=runner \
  --build-arg RUNNER_UID=1001 \
  --build-arg RUNNER_GID=1001 \
  -t forgejo-actions-ubuntu:26.04 .

docker build \
  -f Dockerfile.debian-sid \
  --build-arg APT_MIRROR=https://pkgs.ofkm.us/debian \
  --build-arg APT_SECURITY_MIRROR=https://pkgs.ofkm.us/debian-security \
  --build-arg NODE_MAJOR=24 \
  --build-arg RUNNER_USER=runner \
  --build-arg RUNNER_UID=1001 \
  --build-arg RUNNER_GID=1001 \
  -t forgejo-actions-debian:sid .

APT_MIRROR rewrites the default Ubuntu archive, security, and ports apt sources before the first apt-get update, so Ubuntu packages are fetched through your cache server. For Debian Sid, APT_MIRROR rewrites the main Debian sources and APT_SECURITY_MIRROR rewrites Debian security sources if they exist.

For Docker-in-Docker jobs, run the job container privileged or mount the host Docker socket, depending on how your Forgejo runner is deployed. The image includes the Docker CLI so either model can work.

Workflow values to fill in

The included .forgejo/workflows/build.yml uses the official Docker actions:

• docker/setup-buildx-action@v4
• docker/metadata-action@v6
• docker/login-action@v4
• docker/build-push-action@v7

Fill in these values:

• REGISTRY: the Forgejo registry hostname, for example forgejo.ofkm.us
• IMAGE_NAME: the package path, for example ofkm/actions

The workflow pushes these tags:

${REGISTRY}/${IMAGE_NAME}:ubuntu-26.04
${REGISTRY}/${IMAGE_NAME}:debian-sid