diff --git a/.gitea/workflows/ansible-linters.yaml b/.gitea/workflows/ansible-linters.yaml index cb20869..6dc3337 100644 --- a/.gitea/workflows/ansible-linters.yaml +++ b/.gitea/workflows/ansible-linters.yaml @@ -9,8 +9,7 @@ on: jobs: ansible-lint: - runs-on: - - ubuntu-latest + runs-on: ubuntu-latest steps: - uses: actions/checkout@v6.0.1 - name: Run ansible-lint diff --git a/.kiro/steering/ansible-best-practices.md b/.kiro/steering/ansible-best-practices.md deleted file mode 100644 index 95e9b47..0000000 --- a/.kiro/steering/ansible-best-practices.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -inclusion: always ---- - -# Ansible Best Practices für Act Runner Role - -## Allgemeine Prinzipien - -### Idempotenz - -- Alle Tasks müssen idempotent sein - mehrfache Ausführung führt zum gleichen Ergebnis -- Verwende `changed_when` und `failed_when` für präzise Zustandskontrolle -- Nutze `creates` Parameter bei command/shell Tasks wo möglich - -### Variablen und Namenskonventionen - -- Alle Variablen beginnen mit `act_runner_` als Präfix -- Verwende aussagekräftige Namen: `act_runner_config_file` statt `config_file` -- Dokumentiere alle Variablen mit `## @param` Kommentaren -- Setze sinnvolle Defaults in `defaults/main.yaml` - -### Plattform-Unterstützung - -- Verwende OS-spezifische Variablen in `vars/` Verzeichnis -- Nutze `ansible_facts` für Plattform-Erkennung -- Teste auf allen unterstützten Distributionen - -## Task-Organisation - -### Struktur - -```yaml -- name: Beschreibender Task-Name - ansible.builtin.module_name: - parameter: value - register: variable_name - when: condition - notify: handler_name -``` - -### Fehlerbehandlung - -- Verwende `failed_when` für spezifische Fehlerbedingungen -- Registriere wichtige Outputs mit `register` -- Nutze `assert` für Eingabevalidierung - -### Handler - -- Ein Handler pro Service-Aktion -- Verwende `systemd` Modul für Service-Management -- Handler sollten idempotent sein - -## Sicherheit - -### Berechtigungen - -- Setze explizite Dateiberechtigungen (`mode`) -- Verwende dedizierte Benutzer/Gruppen -- Minimiere privilegierte Operationen - -### Secrets - -- Keine Secrets in Defaults oder Variablen -- Verwende Ansible Vault für sensible Daten -- Dokumentiere erforderliche Secrets klar - -## Testing und Qualität - -### Lint-Regeln - -- Befolge `.ansible-lint` Konfiguration für Ansible Dateien. -- Verwende FQCN (Fully Qualified Collection Names) -- Keine deprecated Module verwenden -- Befolge `.markdownliny.yaml` Konfiguration für Markdown Dateien. - -### Dokumentation - -- Jeder Task braucht einen aussagekräftigen Namen -- Dokumentiere komplexe Logik mit Kommentaren -- README automatisch aus Variablen generieren diff --git a/.kiro/steering/configuration-patterns.md b/.kiro/steering/configuration-patterns.md deleted file mode 100644 index 0dec691..0000000 --- a/.kiro/steering/configuration-patterns.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -inclusion: fileMatch -fileMatchPattern: 'defaults/**/*.yaml' ---- - -# Konfigurationsmuster für Act Runner - -## Variablen-Struktur - -### Hierarchische Konfiguration - -```yaml -act_runner_config: - log: - level: info - runner: - capacity: 1 - labels: [] - container: - privileged: false - options: {} -``` - -### Naming Conventions - -- Präfix: `act_runner_` für alle Variablen -- Verschachtelte Struktur für zusammengehörige Optionen -- Klare, selbsterklärende Namen - -## Konfigurationsmuster - -### Standard-Setup (Minimal) - -```yaml -act_runner_gitea_url: "https://gitea.example.com" -act_runner_token: "{{ vault_act_runner_token }}" -``` - -### Erweiterte Konfiguration - -```yaml -act_runner_config: - runner: - capacity: 3 - labels: - - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest" - - "node-18:docker://node:18-alpine" - - "python-3.11:docker://python:3.11-slim" - container: - privileged: true - network: "runner-network" - valid_volumes: - - "/tmp" - - "/var/run/docker.sock:/var/run/docker.sock" -``` - -### High-Performance Setup - -```yaml -act_runner_config: - runner: - capacity: 5 - timeout: "6h" - fetch_interval: "1s" - cache: - enabled: true - dir: "/var/cache/act_runner" - container: - force_pull: false # Für bessere Performance - docker_timeout: "30s" -``` - -## Template-Patterns - -### Bedingte Konfiguration - -```yaml -# In defaults/main.yaml -act_runner_config: - container: - privileged: "{{ act_runner_privileged_mode | default(false) }}" - docker_host: "{{ act_runner_docker_host | default('') }}" -``` - -### Umgebungsspezifische Overrides - -```yaml -# Für Development -act_runner_config: - runner: - insecure: true # Nur für Dev-Umgebungen - -# Für Production -act_runner_config: - runner: - insecure: false - timeout: "1h" # Kürzere Timeouts in Prod -``` - -## Validierungsmuster - -### Required Variables - -```yaml -# In tasks/verify_vars.yaml -- name: Verify required variables - assert: - that: - - act_runner_gitea_url is defined - - act_runner_gitea_url | length > 0 - - act_runner_token is defined - - act_runner_token | length > 0 -``` - -### Configuration Validation - -```yaml -- name: Validate runner capacity - assert: - that: - - act_runner_config.runner.capacity is number - - act_runner_config.runner.capacity > 0 - - act_runner_config.runner.capacity <= 10 - fail_msg: "Runner capacity must be between 1 and 10" -``` - -## Dokumentationsmuster - -### Variable Documentation - -```yaml -## @param act_runner_config.runner.capacity Execute how many tasks concurrently -## @param act_runner_config.runner.labels The labels determine which jobs can run -## @param act_runner_config.container.privileged Use privileged mode for containers -``` - -### Beispiel-Konfigurationen - -```yaml -# Beispiele in defaults/main.yaml als Kommentare -act_runner_config: - runner: - envs: {} - # Beispiel: - # envs: - # NODE_ENV: production - # CUSTOM_VAR: value -``` \ No newline at end of file diff --git a/.kiro/steering/development-workflow.md b/.kiro/steering/development-workflow.md deleted file mode 100644 index a7306d1..0000000 --- a/.kiro/steering/development-workflow.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -inclusion: always ---- - -# Entwicklungsworkflow für Act Runner Ansible Role - -## Entwicklungsumgebung - -### Voraussetzungen - -- Ansible >= 2.9 -- Node.js >= 16.0.0 (für Dokumentations-Tools) -- Docker (für Testing) -- Molecule (für Role-Testing) - -### Setup - -```bash -# Dependencies installieren -npm install - -# Ansible Collections installieren -ansible-galaxy collection install -r requirements.yml - -# Molecule für Testing -pip install molecule[docker] -``` - -## Code-Änderungen - -### Workflow - -1. **Branch erstellen**: `git checkout -b feature/beschreibung` -2. **Änderungen implementieren** -3. **Tests ausführen** -4. **Dokumentation aktualisieren** -5. **Pull Request erstellen** - -### Task-Entwicklung - -```yaml -# Neue Tasks in tasks/main.yaml hinzufügen -- name: Beschreibender Name der Aktion - ansible.builtin.module: - parameter: "{{ variable }}" - register: result - when: condition - notify: handler_name -``` - -### Variablen hinzufügen - -1. In `defaults/main.yaml` mit `@param` Dokumentation -2. OS-spezifische Werte in `vars/OS.yaml` -3. README automatisch regenerieren: `npm run readme:parameters` - -## Testing - -### Lokales Testing - -```bash -# Syntax Check -ansible-playbook --syntax-check tests/test.yml - -# Lint Check -ansible-lint . - -# YAML Lint -yamllint . - -# Markdown Lint -npm run readme:lint -``` - -### Molecule Testing - -```bash -# Alle Tests -molecule test - -# Nur Syntax -molecule syntax - -# Converge (ohne Destroy) -molecule converge -``` - -## Qualitätssicherung - -### Pre-Commit Checks - -- Ansible Lint muss ohne Fehler durchlaufen -- YAML Syntax muss korrekt sein -- Markdown Dokumentation muss valide sein -- Alle neuen Variablen müssen dokumentiert sein - -### Code Review Kriterien - -- Idempotenz gewährleistet -- Fehlerbehandlung implementiert -- Plattform-Kompatibilität beachtet -- Sicherheits-Best-Practices befolgt -- Tests für neue Funktionalität - -## Release-Prozess - -### Versionierung - -- Semantic Versioning (MAJOR.MINOR.PATCH) -- Tags für Releases -- Changelog pflegen - -### Ansible Galaxy - -```bash -# Role zu Galaxy hochladen -ansible-galaxy role import volker-raschek act-runner-ansible-role -``` - -## Troubleshooting - -### Häufige Probleme - -- **Service startet nicht**: Logs prüfen mit `journalctl -u act_runner` -- **Registrierung fehlgeschlagen**: Token und URL validieren -- **Permission Denied**: Benutzer/Gruppen-Konfiguration prüfen - -### Debug-Modus - -```yaml -# Mehr Ausgaben für Debugging -- debug: - var: variable_name - when: ansible_verbosity >= 2 -``` diff --git a/.kiro/steering/security-guidelines.md b/.kiro/steering/security-guidelines.md deleted file mode 100644 index 00a8058..0000000 --- a/.kiro/steering/security-guidelines.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -inclusion: always ---- - -# Sicherheitsrichtlinien für Act Runner - -## Grundprinzipien - -### Least Privilege - -- Runner läuft unter dediziertem Benutzer (`act_runner`) -- Minimale Berechtigungen für Dateien und Verzeichnisse -- Keine Root-Rechte für Runner-Prozess - -### Isolation - -- Container-basierte Job-Ausführung -- Netzwerk-Isolation wo möglich -- Begrenzte Volume-Mounts - -## Konfigurationssicherheit - -### Secrets Management - -```yaml -# NIEMALS Secrets in Klartext -act_runner_token: "{{ vault_act_runner_token }}" - -# Ansible Vault verwenden -ansible-vault encrypt_string 'secret-token' --name 'vault_act_runner_token' -``` - -### Sichere Defaults - -```yaml -act_runner_config: - runner: - insecure: false # TLS-Verifikation aktiviert - container: - privileged: false # Kein privilegierter Modus - require_docker: true # Docker-Daemon erforderlich -``` - -## Container-Sicherheit - -### Privileged Mode - -```yaml -# Nur wenn unbedingt erforderlich -act_runner_config: - container: - privileged: true - # Dokumentiere WARUM privileged erforderlich ist -``` - -### Volume Restrictions - -```yaml -act_runner_config: - container: - valid_volumes: - - "/tmp" - - "/var/cache" - # NIEMALS: "/", "/etc", "/var/lib" -``` - -### Docker Socket - -```yaml -# Vorsicht bei Docker Socket Mount -valid_volumes: - - "/var/run/docker.sock:/var/run/docker.sock" -# Ermöglicht Container-Escape! -``` - -## Netzwerk-Sicherheit - -### TLS-Konfiguration - -```yaml -act_runner_config: - runner: - insecure: false # Immer TLS verwenden - fetch_timeout: "5s" # Kurze Timeouts -``` - -### Firewall-Regeln - -- Nur ausgehende Verbindungen zu Gitea-Server -- Keine eingehenden Verbindungen erforderlich -- Docker-Netzwerk isolieren - -## Dateisystem-Sicherheit - -### Berechtigungen - -```yaml -# In tasks -- name: Create secure directory - file: - path: "{{ act_runner_lib_dir }}" - owner: "{{ act_runner_unix_user }}" - group: "{{ act_runner_unix_group }}" - mode: "0750" # Keine world-readable -``` - -### Sensitive Files - -```yaml -- name: Template config with restricted permissions - template: - src: config.yaml.j2 - dest: "{{ act_runner_config_file }}" - mode: "0640" # Nur Owner und Group -``` - -## Monitoring und Logging - -### Log-Sicherheit - -```yaml -act_runner_config: - log: - level: info # Nicht debug in Production -``` - -### Audit-Trail - -- Alle Runner-Registrierungen loggen -- Service-Status überwachen -- Fehlgeschlagene Jobs protokollieren - -## Incident Response - -### Kompromittierung - -1. Runner-Service stoppen -2. Token widerrufen in Gitea -3. Logs analysieren -4. System neu aufsetzen -5. Neuen Token generieren - -### Verdächtige Aktivitäten - -- Unerwartete Container-Images -- Excessive Resource Usage -- Netzwerk-Verbindungen zu unbekannten Hosts - -## Compliance - -### Datenverarbeitung - -- Keine persistente Speicherung von Job-Daten -- Temporäre Dateien nach Job-Ende löschen -- Logs rotieren und archivieren - -### Zugriffskontrolle - -- Dokumentiere wer Zugriff auf Runner-Token hat -- Regelmäßige Token-Rotation -- Prinzip der minimalen Berechtigung \ No newline at end of file diff --git a/.kiro/steering/testing-strategy.md b/.kiro/steering/testing-strategy.md deleted file mode 100644 index 23acf45..0000000 --- a/.kiro/steering/testing-strategy.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -inclusion: fileMatch -fileMatchPattern: 'tests/**/*' ---- - -# Testing-Strategie für Act Runner Role - -## Test-Pyramide - -### Unit Tests (Syntax/Lint) - -```bash -# Ansible Syntax -ansible-playbook --syntax-check tests/test.yml - -# Ansible Lint -ansible-lint . - -# YAML Lint -yamllint . -``` - -### Integration Tests (Molecule) - -```bash -# Vollständiger Test-Zyklus -molecule test - -# Einzelne Schritte -molecule create # Test-Umgebung erstellen -molecule converge # Role ausführen -molecule verify # Tests ausführen -molecule destroy # Aufräumen -``` - -### End-to-End Tests - -- Runner registriert sich erfolgreich -- Service startet und läuft stabil -- Jobs können ausgeführt werden - -## Molecule-Konfiguration - -### molecule.yml - -```yaml -dependency: - name: galaxy -driver: - name: docker -platforms: - - name: ubuntu-20.04 - image: ubuntu:20.04 - pre_build_image: true - - name: archlinux - image: archlinux:latest - pre_build_image: true -provisioner: - name: ansible - config_options: - defaults: - callbacks_enabled: profile_tasks -verifier: - name: ansible -``` - -### Test Scenarios - -```yaml -# molecule/default/converge.yml -- name: Converge - hosts: all - become: true - vars: - act_runner_gitea_url: "https://gitea.example.com" - act_runner_token: "test-token" - roles: - - role: act_runner -``` - -## Testfälle - -### Positive Tests - -- Installation auf unterstützten OS -- Konfiguration mit Standard-Werten -- Service-Start und -Status -- Registrierung (gemockt) - -### Negative Tests - -- Fehlende Required Variables -- Ungültige Gitea-URL -- Ungültiger Token -- Unzureichende Berechtigungen - -### Edge Cases - -- Bereits registrierter Runner -- Service bereits gestartet -- Konfigurationsdatei existiert bereits - -## Testdaten - -### Mock-Konfigurationen - -```yaml -# Minimal -act_runner_gitea_url: "https://test.gitea.com" -act_runner_token: "test-token-123" - -# Erweitert -act_runner_config: - runner: - capacity: 2 - labels: - - "test:docker://alpine:latest" -``` - -### Test-Inventories - -```ini -[runners] -test-ubuntu ansible_host=ubuntu-container -test-arch ansible_host=arch-container - -[runners:vars] -ansible_connection=docker -``` - -## Verifikation - -### Service Tests - -```yaml -# In molecule/default/verify.yml -- name: Verify service is running - service_facts: - -- name: Check act_runner service - assert: - that: - - ansible_facts.services['act_runner.service'].state == 'running' - - ansible_facts.services['act_runner.service'].status == 'enabled' -``` - -### Configuration Tests - -```yaml -- name: Verify config file exists - stat: - path: /etc/act_runner/config.yaml - register: config_file - -- name: Check config file - assert: - that: - - config_file.stat.exists - - config_file.stat.mode == '0644' -``` - -### Process Tests - -```yaml -- name: Check act_runner process - command: pgrep -f act_runner - register: runner_process - failed_when: runner_process.rc != 0 -``` - -## CI/CD Integration - -### GitHub Actions - -```yaml -name: Test Role -on: [push, pull_request] -jobs: - test: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: Run Molecule - run: molecule test -``` - -### Gitea Actions - -```yaml -name: Ansible Role Test -on: [push] -jobs: - molecule: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v3 - - name: Test with Molecule - run: | - pip install molecule[docker] - molecule test -``` - -## Performance Tests - -### Resource Usage - -- Memory consumption des Runners -- CPU-Last während Job-Ausführung -- Disk I/O für Container-Images - -### Scalability - -- Mehrere Runner auf einem Host -- Concurrent Job-Ausführung -- Container-Startup-Zeit - -## Regression Tests - -### Upgrade-Tests - -- Update von vorheriger Version -- Konfigurationsmigration -- Service-Kontinuität - -### Compatibility Tests - -- Verschiedene Ansible-Versionen -- Verschiedene OS-Versionen -- Verschiedene Docker-Versionen diff --git a/README.md b/README.md index 8a2539e..e8f6921 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # act_runner -This Ansible role installs and configures a Gitea Act Runner for executing GitHub Actions-compatible workflows. +This Ansible role installs and configures a gitea Act Runner for executing GitHub Actions-compatible workflows. ## Installation @@ -74,9 +74,9 @@ Found roles matching your search: | `act_runner_config.runner.env_file` | Extra environment variables to run jobs from a file | `.env` | | `act_runner_config.runner.timeout` | The timeout for a job to be finished | `3h` | | `act_runner_config.runner.shutdown_timeout` | The timeout for the runner to wait for running jobs to finish when shutting down | `0s` | -| `act_runner_config.runner.insecure` | Whether skip verifying the TLS certificate of the Gitea instance | `false` | -| `act_runner_config.runner.fetch_timeout` | The timeout for fetching the job from the Gitea instance | `5s` | -| `act_runner_config.runner.fetch_interval` | The interval for fetching the job from the Gitea instance | `2s` | +| `act_runner_config.runner.insecure` | Whether skip verifying the TLS certificate of the gitea instance | `false` | +| `act_runner_config.runner.fetch_timeout` | The timeout for fetching the job from the gitea instance | `5s` | +| `act_runner_config.runner.fetch_interval` | The interval for fetching the job from the gitea instance | `2s` | | `act_runner_config.runner.github_mirror` | The mirror address of the github that pulls the action repository | `""` | | `act_runner_config.runner.labels` | The labels of a runner are used to determine which jobs the runner can run | `["ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest","ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04","ubuntu-20.04:docker://docker.gitea.com/runner-images:ubuntu-20.04"]` | | `act_runner_config.cache.enabled` | Enable cache server to use actions/cache | `true` | @@ -95,5 +95,5 @@ Found roles matching your search: | `act_runner_config.container.require_docker` | Always require a reachable docker daemon | `false` | | `act_runner_config.container.docker_timeout` | Timeout to wait for the docker daemon to be reachable | `0s` | | `act_runner_config.host.workdir_parent` | The parent directory of a job's working directory | `nil` | -| `act_runner_gitea_url` | The URL of the Gitea instance | `""` | +| `act_runner_gitea_url` | The URL of the gitea instance | `""` | | `act_runner_token` | The registration token for the act_runner | `""` | diff --git a/tasks/verify_vars.yaml b/tasks/verify_vars.yaml index a1e2d83..695dee7 100644 --- a/tasks/verify_vars.yaml +++ b/tasks/verify_vars.yaml @@ -3,9 +3,9 @@ - name: Verify required variables are defined ansible.builtin.assert: that: - - vars[item] is defined - - vars[item] | length > 0 + - lookup('vars', item) is defined + - lookup('vars', item) | length > 0 fail_msg: "Required variable '{{ item }}' is not defined or empty." - with_items: + loop: - act_runner_gitea_url - act_runner_token