labFusion/docs/RUNNER_LABELS.md

# Gitea Actions Runner Labels - Technical Summary

Based on the [Gitea Actions Design Documentation](https://docs.gitea.com/usage/actions/design#act-runner), 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:

```bash
# 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`)
```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`)
```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`)
```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`)
```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:
```yaml
# ✅ 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:
```yaml
# ❌ 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:

```yaml
# 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](https://docs.gitea.com/usage/actions/design#act-runner)
- [LabFusion Runners Setup](RUNNERS.md)
- [LabFusion CI/CD Pipelines](CI_CD.md)