Refactor CI workflows to reorder runner labels for improved clarity and consistency across API Docs, API Gateway, Service Adapters, Frontend, and Integration Tests; update documentation to include new runner labels and optimization recommendations.

2025-09-13 01:16:32 +02:00
parent 28bd40b8d0
commit e55c642db2
14 changed files with 989 additions and 19 deletions
--- a/docs/RUNNER_LABELS.md
+++ b/docs/RUNNER_LABELS.md
@@ -0,0 +1,180 @@
+# 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:
+  - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "heavy:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "java:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "python:docker://docker.gitea.com/runner-images:ubuntu-latest"
+```
+
+### Light Runner (`config_light.yaml`)
+```yaml
+labels:
+  - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "light:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "nodejs:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "frontend:docker://docker.gitea.com/runner-images:ubuntu-latest"
+```
+
+### Docker Runner (`config_docker.yaml`)
+```yaml
+labels:
+  - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "docker:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "integration:docker://docker.gitea.com/runner-images:ubuntu-latest"
+```
+
+### Security Runner (`config_security.yaml`)
+```yaml
+labels:
+  - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "self-hosted:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "security:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  - "scan: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)