---
title: "Action Runner"
linkTitle: "Runner"
weight: 20
description: >
  Self-hosted runner infrastructure with orchestration capabilities
---

{{% alert title="Draft" color="warning" %}}
**Editorial Status**: This page is currently being developed.

* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
* **Assignee**: [Name or Team]
* **Status**: Draft
* **Last Updated**: YYYY-MM-DD
* **TODO**:
  * [ ] Add detailed component description
  * [ ] Include usage examples and code samples
  * [ ] Add architecture diagrams
  * [ ] Review and finalize content
{{% /alert %}}

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

* [Feature 1]
* [Feature 2]
* [Feature 3]

## 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**: 
- [Runner on edge connect using GARM](https://edp.buildth.ing/DevFW-CICD/garm-provider-edge-connect/src/branch/main/runner)
- [Static runner](https://edp.buildth.ing/DevFW-CICD/stacks/src/branch/main/template/stacks/forgejo/forgejo-runner/dind-docker.yaml)

**Documentation**: [Forgejo Runner installation guide](https://forgejo.org/docs/latest/admin/actions/runner-installation/)

## 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`
* Kubernetes cluster

### Quick Start

1. Download [Kubernetes manifest](https://edp.buildth.ing/DevFW-CICD/stacks/src/branch/main/template/stacks/forgejo/forgejo-runner/dind-docker.yaml)
2. Replace `${RUNNER_SECRET}` with the runner registration token
3. Replace `${RUNNER_NAME}` with the name the runner should have
4. Replace `${FORGEJO_INSTANCE_URL}` with the instance url
5. (if namespace does not exists) `kubectl create ns gitea`
6. 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

```mermaid
---
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
    end
```

### Deployment Architecture

[Add infrastructure and deployment diagrams showing how the component is deployed]

## Configuration

There is a sophisticated [configuration file](https://forgejo.org/docs/latest/admin/actions/runner-installation/#configuration), 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](https://edp.buildth.ing/DevFW-CICD/stacks/src/branch/main/template/stacks/forgejo/forgejo-runner/dind-docker.yaml)). 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`](https://forgejo.org/docs/latest/admin/actions/security/#job-containers-w-lxc) and [`host`](https://forgejo.org/docs/latest/admin/actions/security/#execution-on-host-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** in a non root environment. You can find examples here: [Examples](https://github.com/moby/buildkit/tree/master/examples/kubernetes).

***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**: [Production / Beta / Experimental]

## Additional Resources

* [Forgejo Runner installation guide](https://forgejo.org/docs/latest/admin/actions/runner-installation)
* [Static Runners on Kubernetes](https://edp.buildth.ing/DevFW-CICD/stacks/src/branch/main/template/stacks/forgejo/forgejo-runner/dind-docker.yaml)
* [Runner Orchestartion using GARM on Edge Connect](../runner-orchestration)

## Documentation Notes

[Instructions for team members filling in this documentation - remove this section once complete]