Overview
Action runners are the execution environment for Forgejo Actions workflows. By design, runners execute remote code submitted through CI/CD pipelines, making their architecture highly dependent on the underlying infrastructure and security requirements.
The primary objective in any runner setup is the separation and isolation of individual runs. Since runners are specifically built to execute arbitrary code from repositories, proper isolation is critical to prevent data and secret leakage between different pipeline executions. Each runner must be thoroughly cleaned or recreated after every job to ensure no residual data persists that could compromise subsequent runs.
Beyond isolation concerns, action runners represent high-value targets for supply chain attacks. Runners frequently compile, build, and package software binaries that may be distributed to thousands or millions of end users. Compromising a runner could allow attackers to inject malicious code directly into the software supply chain, making runner security a critical consideration in any deployment.
This document explores different runner architectures, examining their security characteristics, operational trade-offs, and suitability for various infrastructure environments and showing off an example deployment using a Containerized Kubernetes environment.
Key Features
- Consistent environment for Forgejo Actions
- Primary location to execute code e.g. deployments
- Good security practices essential due to broad remit
Purpose in EDP
A actions runner are executing Forgejo actions, which can be used to build, test, package and deploy software. To ensure that EDP customers do not need to provision their own action runners with high efford, we provide globally registered actions runners to pick up jobs.
Repository
Code:
Documentation: Forgejo Runner installation guide
Runner Setups
Different runner deployment architectures offer varying levels of isolation, security, and operational complexity. The choice depends on your infrastructure capabilities, security requirements, and operational overhead tolerance.
On Bare Metal
Bare metal runners execute directly on physical hardware without virtualization layers.
Advantages:
- Maximum performance with direct hardware access
- Complete hardware isolation between different physical machines
- No hypervisor overhead or virtualization complexity
Disadvantages:
- Difficult to clean after each run, requiring manual intervention or full OS reinstallation
- Long provisioning time for individual runners
- Complex provisioning processes requiring physical access or remote management tools
- Limited scalability due to physical hardware constraints
- Higher risk of persistent contamination between runs
Use case: Best suited for specialized workloads requiring specific hardware, performance-critical builds, or environments where virtualization is not available.
On Virtual Machines
VM-based runners operate within virtualized environments managed by a hypervisor.
Advantages:
- Strong isolation through hypervisor and hardware memory mapping
- Virtual machine images enable faster provisioning compared to bare metal
- Easy to snapshot, clone, and restore to clean states
- Better resource utilization through multiple VMs per physical host
- Automated cleanup by destroying and recreating VMs after each run
Disadvantages:
- Requires hypervisor infrastructure and management
- Slower provisioning than containers
- Higher resource overhead compared to containerized solutions
- More complex orchestration for scaling runner fleets
Use case: Ideal for environments requiring strong isolation guarantees, multi-tenant scenarios, or when running untrusted code from external contributors.
In Containerized Environment
Container-based runners execute within isolated containers using OCI-compliant runtimes.
Advantages:
- Kernel-level isolation using Linux namespaces and cgroups
- Fast provisioning and startup times
- Easy deployment through standardized OCI container images
- Lightweight resource usage enabling high-density runner deployments
- Simple orchestration with Kubernetes or Docker Compose
Disadvantages:
- Weaker isolation than VMs since containers share the host kernel
- Requires elevated permissions or privileged access for certain workflows (e.g., Docker-in-Docker)
- Potential kernel-level vulnerabilities affect all containers on the host
- Container escape vulnerabilities pose security risks in multi-tenant environments
Use case: Best for high-volume CI/CD workloads, trusted code repositories, and environments prioritizing speed and efficiency over maximum isolation.
Getting Started
Prerequisites
- Forgejo instance
- Runner registration token has been generated for a given scope
- Global runners in
admin settings > actions > runner > Create new runner - Organization runners in
organization settings > actions > runner > Create new runner - Repository runners in
repository settings > actions > runner > Create new runner
- Global runners in
- Kubernetes cluster
Quick Start
- Download Kubernetes manifest
- Replace
${RUNNER_SECRET}with the runner registration token - Replace
${RUNNER_NAME}with the name the runner should have - Replace
${FORGEJO_INSTANCE_URL}with the instance url - (if namespace does not exists)
kubectl create ns gitea - Run
kubectl apply -f <file>
Verification
Take a look at the runners page, where you generated the token. There should be 3 runners in idle state now.
Sequence Diagrams
---
title: Forgejo Runner executed in daemon mode
---
sequenceDiagram
Runner->>Forgejo: Register runner
loop Job Workflow
Runner->>Forgejo: Fetch job
Runner->>Runner: Work on job
Runner->>Forgejo: Send result
endDeployment Architecture
[Add infrastructure and deployment diagrams showing how the component is deployed]
Configuration
There is a sophisticated configuration file, where finetuning can be done. The most important thing is done by using labels to define the execution environment.
The label ubuntu-latest:docker://ghcr.io/catthehacker/ubuntu:act-22.04 (as used in example runner). That a job that uses ubuntu-latest label will be executed as docker container inside the ghcr.io/catthehacker/ubuntu:act-22.04 image.
Alternatives to docker are lxc and host.
Troubleshooting
In containerized environments, I want to build container images
Problem: In containerized environment, containers usually do not have many privileges. To start or build containers additional privleges, usually root is required inside of the kernel, the container runtime needs to manage linux namespaces and cgroups.
Solution: A partial solution for this is buildkitd utilizing rootlesskit. This allows containers to be built (but not run) in a non root environment. Several examples can be found in the official buildkit repo.
Rootless vs User namespaces:
As of Kubernetes 1.33, uid mapping can be enabled for pods using pod.spec.hostUsers: false utilizing user namespaces to map user and group ids between the container ids (0-65535) to high host ids (0-65535 + n * 65536) where n is an arbitrary number of containers. This allows that the container runs with actual root permission in its user namespace without being root on the host system.
Rootless is considered the more secure version, as the executable is mapped to a privileged entitiy at all.
Status
Maturity: Beta