GitHub - vegardit/docker-gitea-act-runner: Docker image based on debian:stable-slim to run Gitea's act_runner as a Docker container (original) (raw)

1. What is it?
2. Usage
3. License

What is it?

Multi-arch Docker image based on debian:stable-slim containing Gitea's Action Runner

Why not using Alpine Linux?

• musl-libc - Alpine's Greatest Weakness https://www.linkedin.com/pulse/musl-libc-alpines-greatest-weakness-rogan-lynch
• Why I will never use Alpine Linux ever again https://martinheinz.dev/blog/92
• Does Alpine have known DNS issue within Kubernetes? https://stackoverflow.com/questions/65181012/
• Why is the Alpine Docker image over 50% slower than the Ubuntu image? https://superuser.com/questions/1219609/
• Performance issue with alpine musl library https://unix.stackexchange.com/questions/729342/

Usage

The docker image comes in three flavors:

• vegardit/gitea-act-runner:latest: contains only Gitea Runner and executes workflows in sibling containers on the Docker engine that runs the runner container itself (DooD / Docker-out-of-Docker approach)
• vegardit/gitea-act-runner:dind-latest: executes workflows using an embedded docker engine (DinD / Docker-in-Docker approach) providing better process isolation
• vegardit/gitea-act-runner:dind-rootless-latest: executes workflows using an embedded docker engine (DinD / Docker-in-Docker approach) running the docker daemon as a non-root user (Rootless mode)

Docker Run

Running from the command line:

• Docker-out-of-Docker approach
  docker run \
  -e GITEA_INSTANCE_URL=https://gitea.example.com \
  -e GITEA_RUNNER_REGISTRATION_TOKEN= \
  --name gitea_act_runner \
  -v /var/run/docker.sock:/var/run/docker.sock:rw \
  vegardit/gitea-act-runner:latest
• Docker-in-Docker approach
  docker run \
  -e GITEA_INSTANCE_URL=https://gitea.example.com \
  -e GITEA_RUNNER_REGISTRATION_TOKEN= \
  --name gitea_act_runner \
  --privileged \
  vegardit/gitea-act-runner:dind-latest
• Docker-in-Docker approach with Docker daemon running as a non-root user (Rootless mode)
  docker run \
  -e GITEA_INSTANCE_URL=https://gitea.example.com \
  -e GITEA_RUNNER_REGISTRATION_TOKEN= \
  --name gitea_act_runner \
  --security-opt seccomp=unconfined \
  --security-opt apparmor=unconfined \
  --security-opt systempaths=unconfined \
  vegardit/gitea-act-runner:dind-rootless-latest

Docker Compose

Example docker-compose.yml:

• Docker-out-of-Docker approach

https://docs.docker.com/compose/compose-file/

services:
gitea_act_runner:
image: vegardit/gitea-act-runner:latest
#image: ghcr.io/vegardit/gitea-act-runner:latest
restart: always
volumes:
- /var/run/docker.sock:/var/run/docker.sock:rw
- /my/path/to/data/dir:/data:rw # the config file is located at /data/.runner and needs to survive container restarts
environment:
TZ: "Europe/Berlin"
# config parameters for initial runner registration:
GITEA_INSTANCE_URL: 'https://gitea.example.com' # required
GITEA_RUNNER_REGISTRATION_TOKEN_FILE: 'path/to/file' # one-time registration token, only required on first container start
# or: GITEA_RUNNER_REGISTRATION_TOKEN: ''

• Docker-in-Docker approach

https://docs.docker.com/compose/compose-file/

services:
gitea_act_runner:
image: vegardit/gitea-act-runner:dind-latest
#image: ghcr.io/vegardit/gitea-act-runner:dind-latest
privileged: true
restart: always
volumes:
- /my/path/to/data/dir:/data:rw # the config file is located at /data/.runner and needs to survive container restarts
environment:
TZ: "Europe/Berlin"
# config parameters for initial runner registration:
GITEA_INSTANCE_URL: 'https://gitea.example.com' # required
GITEA_RUNNER_REGISTRATION_TOKEN_FILE: 'path/to/file' # one-time registration token, only required on first container start
# or: GITEA_RUNNER_REGISTRATION_TOKEN: ''

• Docker-in-Docker rootless approach

https://docs.docker.com/compose/compose-file/

services:
gitea_act_runner:
image: vegardit/gitea-act-runner:dind-rootless-latest
#image: ghcr.io/vegardit/gitea-act-runner:dind-rootless-latest
restart: always
security_opt:
- seccomp:unconfined
- apparmor:unconfined
- systempaths=unconfined
volumes:
- /my/path/to/data/dir:/data:rw # the config file is located at /data/.runner and needs to survive container restarts
environment:
TZ: "Europe/Berlin"
# config parameters for initial runner registration:
GITEA_INSTANCE_URL: 'https://gitea.example.com' # required
GITEA_RUNNER_REGISTRATION_TOKEN_FILE: 'path/to/file' # one-time registration token, only required on first container start
# or: GITEA_RUNNER_REGISTRATION_TOKEN: ''

Kubernetes Deployment

Example deployment for Kubernetes:

• Docker-out-of-Docker approach (requires access to host Docker socket)
  apiVersion: apps/v1
  kind: Deployment
  metadata:
  name: gitea-act-runner
  spec:
  replicas: 1
  selector:
  matchLabels:
  app: gitea-act-runner
  template:
  metadata:
  labels:
  app: gitea-act-runner
  spec:
  containers:
  - name: runner
  image: vegardit/gitea-act-runner:latest
  env:
  - name: GITEA_INSTANCE_URL
  value: "https://gitea.example.com"
  - name: GITEA_RUNNER_REGISTRATION_TOKEN
  valueFrom:
  secretKeyRef:
  name: gitea-runner-secret
  key: registration-token
  volumeMounts:
  - name: docker-sock
  mountPath: /var/run/docker.sock
  - name: data
  mountPath: /data
  volumes:
  - name: docker-sock
  hostPath:
  path: /var/run/docker.sock
  type: Socket
  - name: data
  persistentVolumeClaim:
  claimName: gitea-runner-pvc

apiVersion: v1
kind: Secret
metadata:
name: gitea-runner-secret
type: Opaque
stringData:
registration-token: ""

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: gitea-runner-pvc
spec:
accessModes:

• ReadWriteOnce
  resources:
  requests:
  storage: 10Gi

• Docker-in-Docker approach (more secure, doesn't require host Docker access)
  apiVersion: apps/v1
  kind: Deployment
  metadata:
  name: gitea-act-runner-dind
  spec:
  replicas: 1
  selector:
  matchLabels:
  app: gitea-act-runner-dind
  template:
  metadata:
  labels:
  app: gitea-act-runner-dind
  spec:
  containers:
  - name: runner
  image: vegardit/gitea-act-runner:dind-latest
  securityContext:
  privileged: true
  env:
  - name: GITEA_INSTANCE_URL
  value: "https://gitea.example.com"
  - name: GITEA_RUNNER_REGISTRATION_TOKEN
  valueFrom:
  secretKeyRef:
  name: gitea-runner-secret
  key: registration-token
  volumeMounts:
  - name: data
  mountPath: /data
  - name: docker-storage
  mountPath: /var/lib/docker
  volumes:
  - name: data
  persistentVolumeClaim:
  claimName: gitea-runner-data-pvc
  - name: docker-storage
  emptyDir: {}

Notes for Kubernetes deployments:

• For production, prefer the DinD (rootful) approach over DooD because it avoids exposing the host Docker socket and provides better isolation from the host.
• DinD-rootless is generally not recommended in Kubernetes because:
  • It often requires permissive settings (seccompProfile: Unconfined, AppArmor unconfined) that many clusters disallow under their Pod Security Standards.
  • It provides limited additional security at the pod boundary compared to rootful DinD, while still needing relaxed sandboxing.
  • It has practical limitations (user-mode networking via slirp4netns, port publishing quirks, performance trade-offs, storage driver constraints such as fuse-overlayfs).
  • If you need "rootless" semantics, consider using native Kubernetes Jobs (or a Kubernetes-native runner/executor) instead of running a Docker daemon inside the pod.

Additional environment variables

The following environment variables can be specified to further configure the service.

Runner registration:

Runner runtime config:

Runner config template variables

The following environment variables are referenced in the /opt/config.template.yaml file.

Embedded cache server:

Metrics:

License

All files in this repository are released under the Apache License 2.0.

Individual files contain the following tag instead of the full license text:

SPDX-License-Identifier: Apache-2.0

This enables machine processing of license information based on the SPDX License Identifiers that are available here: https://spdx.org/licenses/.