labFusion/docs/RUNNER_LABELS.md

Gitea Actions Runner Labels - Technical Summary

Based on the Gitea Actions Design Documentation, this document summarizes how runner labels work in Gitea Actions.

Overview

Gitea Actions uses a label-based system to match workflow jobs with appropriate runners. The runs-on: ubuntu-latest directive in workflow files means the job will run on a runner that has the ubuntu-latest label.

Label Format

Runner labels follow the format: label[:schema[:args]]

Schema Types

1. host (default): Run jobs directly on the host machine

   • my_custom_label:host - Run on host
   • my_custom_label - Same as above (host is default)

2. docker: Run jobs in Docker containers

   • my_custom_label:docker://node:18 - Run in Node.js 18 container
   • my_custom_label:docker://centos:7 - Run in CentOS 7 container

3. vm (example, not implemented): Run in virtual machines

   • my_custom_label:vm:ubuntu-latest - Run in Ubuntu VM

Label Mapping

When registering a runner, you specify which labels it can handle and how:

# Example registration with custom labels
act_runner register \
  --labels "ubuntu-latest:docker://ubuntu:22.04,self-hosted:host,heavy:docker://ubuntu:22.04"

This means:

• Jobs with runs-on: ubuntu-latest → Run in Ubuntu 22.04 Docker container
• Jobs with runs-on: self-hosted → Run directly on host
• Jobs with runs-on: heavy → Run in Ubuntu 22.04 Docker container

LabFusion Implementation

For the LabFusion project, our runners use these labels:

Heavy Runner

• Labels: ubuntu-latest,self-hosted,heavy,java,python
• Purpose: Java Spring Boot and Python FastAPI workloads
• Configuration: Uses Docker containers for isolation
• Config File: config_heavy.yaml

Light Runner

• Labels: ubuntu-latest,self-hosted,light,nodejs,frontend
• Purpose: Node.js and React frontend workloads
• Configuration: Uses Docker containers for isolation
• Config File: config_light.yaml

Docker Runner

• Labels: ubuntu-latest,self-hosted,docker,integration
• Purpose: Integration tests and Docker builds
• Configuration: Full Docker-in-Docker capabilities
• Config File: config_docker.yaml

Security Runner

• Labels: ubuntu-latest,self-hosted,security,scan
• Purpose: Security scans and vulnerability assessments
• Configuration: Specialized for security tools
• Config File: config_security.yaml

Label Mapping in Config Files

Each runner configuration file maps labels to Docker images:

Heavy Runner (config_heavy.yaml)

labels:
  # Primary optimized images (checked first)
  - "java:docker://openjdk:17-jdk-slim"
  - "python:docker://python:3.11-slim"
  - "heavy:docker://openjdk:17-jdk-slim"
  # Fallback images (checked last)
  - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
  - "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-latest"

Light Runner (config_light.yaml)

labels:
  # Primary optimized images (checked first)
  - "nodejs:docker://node:20-slim"
  - "frontend:docker://node:20-slim"
  - "light:docker://node:20-slim"
  # Fallback images (checked last)
  - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
  - "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-latest"

Docker Runner (config_docker.yaml)

labels:
  # Primary optimized images (checked first)
  - "docker:docker://docker:24-dind"
  - "integration:docker://docker:24-dind"
  # Fallback images (checked last)
  - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
  - "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-latest"

Security Runner (config_security.yaml)

labels:
  # Primary optimized images (checked first)
  - "security:docker://alpine:3.19"
  - "scan:docker://alpine:3.19"
  # Fallback images (checked last)
  - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
  - "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-latest"

Label Priority and Matching

Important: The order of labels in runs-on matters! Gitea checks labels in order and uses the first match.

Optimized Approach:

# ✅ GOOD: Specific labels first, fallback last
runs-on: [java, heavy, self-hosted]

This will match:

1. java:docker://... (optimized Java image) ✅
2. heavy:docker://... (if java not available)
3. self-hosted:docker://... (fallback to full Ubuntu)

Avoid This:

# ❌ BAD: Generic labels first
runs-on: [self-hosted, heavy, java]

This will match:

1. self-hosted:docker://... (full Ubuntu image) ❌
2. Never reaches the optimized java label

Workflow Usage

In our CI/CD workflows, jobs specify which runner to use:

# API Gateway (Java) - uses optimized Java image
runs-on: [java, heavy, self-hosted]

# Service Adapters (Python) - uses optimized Python image
runs-on: [python, heavy, self-hosted]

# API Docs (Node.js) - uses optimized Node.js image
runs-on: [nodejs, light, self-hosted]

# Frontend (React) - uses optimized Node.js image
runs-on: [frontend, light, self-hosted]

# Integration Tests - uses optimized Docker image
runs-on: [docker, integration, self-hosted]

# Security Scans - uses optimized security image
runs-on: [security, scan, self-hosted]

Key Benefits

1. Flexibility: Mix and match labels for different workload types
2. Isolation: Docker containers provide job isolation
3. Resource Management: Different runners can have different resource limits
4. Specialization: Dedicated runners for specific tasks (security, integration)
5. Scalability: Easy to add more runners with specific label combinations

Best Practices

1. Use descriptive labels that clearly indicate the runner's purpose
2. Combine multiple labels to allow flexible job assignment
3. Use Docker containers for better isolation and consistency
4. Match labels to workflow requirements for optimal resource usage
5. Consider resource limits when assigning labels to runners

References

• Gitea Actions Design Documentation
• LabFusion Runners Setup
• LabFusion CI/CD Pipelines