Adding gitea act_runner roles

ansible/group_vars/all/vars.yml

@@ -89,6 +89,13 @@ roundcube_smtp_port: "587"
 #     ssl: true           # default: true
 #     keep: true          # default: true — set false to delete from source after fetch
 
+# Gitea Actions runners (act_runner with Docker executor)
+act_runner_version: "latest"
+act_runner_data_dir: /opt/act_runner
+act_runner_count: 3
+# Secrets — store values in ansible/group_vars/all/vault.yml (Ansible Vault)
+# gitea_runner_registration_token: ""  # Gitea admin → Site Administration → Runners → Create runner token
+
 # Container registry (Docker Registry v2)
 registry_data_dir: /opt/registry
 # Registry users — plaintext passwords, Ansible generates bcrypt hashes at deploy time

ansible/roles/act_runner/handlers/main.yml

@@ -0,0 +1,7 @@
+---
+- name: Restart act_runner
+  community.docker.docker_compose_v2:
+    project_src: "{{ act_runner_data_dir }}"
+    state: present
+    pull: missing
+    recreate: always

ansible/roles/act_runner/tasks/main.yml

@@ -0,0 +1,46 @@
+---
+- name: Create act_runner base directory
+  ansible.builtin.file:
+    path: "{{ act_runner_data_dir }}"
+    state: directory
+    owner: root
+    group: root
+    mode: "0755"
+  tags: act_runner
+
+- name: Create per-runner data directories
+  ansible.builtin.file:
+    path: "{{ act_runner_data_dir }}/runner-{{ item }}"
+    state: directory
+    owner: root
+    group: root
+    mode: "0755"
+  loop: "{{ range(1, act_runner_count + 1) | list }}"
+  tags: act_runner
+
+- name: Deploy act_runner config
+  ansible.builtin.template:
+    src: config.yml.j2
+    dest: "{{ act_runner_data_dir }}/config.yml"
+    owner: root
+    group: root
+    mode: "0644"
+  notify: Restart act_runner
+  tags: act_runner
+
+- name: Deploy Docker Compose file
+  ansible.builtin.template:
+    src: docker-compose.yml.j2
+    dest: "{{ act_runner_data_dir }}/docker-compose.yml"
+    owner: root
+    group: root
+    mode: "0644"
+  notify: Restart act_runner
+  tags: act_runner
+
+- name: Start act_runner
+  community.docker.docker_compose_v2:
+    project_src: "{{ act_runner_data_dir }}"
+    state: present
+    pull: missing
+  tags: act_runner

ansible/roles/act_runner/templates/config.yml.j2

@@ -0,0 +1,21 @@
+# Managed by Ansible — do not edit manually
+log:
+  level: info
+
+runner:
+  file: .runner        # stored in each runner's /data volume
+  capacity: 1          # one concurrent job per runner container
+  timeout: 3h
+  fetch_timeout: 5s
+  fetch_interval: 2s
+
+cache:
+  enabled: false       # disable built-in cache server; use actions/cache if needed
+
+container:
+  network: bridge      # job containers get default bridge network with internet access
+  privileged: false
+  valid_volumes:
+    - /tmp
+  force_pull: false
+  force_rebuild: false

ansible/roles/act_runner/templates/docker-compose.yml.j2

@@ -0,0 +1,17 @@
+# Managed by Ansible — do not edit manually
+services:
+{% for i in range(1, act_runner_count + 1) %}
+  runner-{{ i }}:
+    image: gitea/act_runner:{{ act_runner_version }}
+    container_name: act-runner-{{ i }}
+    restart: unless-stopped
+    environment:
+      - GITEA_INSTANCE_URL=https://{{ domain_gitea }}
+      - GITEA_RUNNER_REGISTRATION_TOKEN={{ gitea_runner_registration_token }}
+      - GITEA_RUNNER_NAME=runner-{{ i }}
+      - CONFIG_FILE=/config.yml
+    volumes:
+      - {{ act_runner_data_dir }}/runner-{{ i }}:/data
+      - {{ act_runner_data_dir }}/config.yml:/config.yml:ro
+      - /var/run/docker.sock:/var/run/docker.sock
+{% endfor %}

ansible/site.yml

@@ -7,6 +7,7 @@
     - docker
     - traefik
     - gitea
+    - act_runner
     - nextcloud
     - sso
     - mail

docs/runbook-configuration.md

@@ -209,6 +209,55 @@ With the alias in place you can use the shorter SCP-like URL:
 git clone git@gitea.ladkau.de:<username>/myrepo.git
 ```
 
+### 3.4 Deploy Gitea Actions runners
+
+Three `act_runner` containers (Docker executor) are provisioned by the
+`act_runner` Ansible role. Each runner handles one concurrent job; together
+they allow up to three parallel workflow jobs.
+
+**This step requires Gitea to be running and the admin account to exist
+(step 3.1). Runners cannot register until a token is obtained from Gitea.**
+
+**Step 1 — Get a runner registration token**
+
+1. Go to `https://gitea.ladkau.de` → sign in as admin.
+2. Navigate to **Site Administration** (top-right menu) →
+   **Actions** → **Runners**.
+3. Click **Create runner token** and copy the token.
+
+**Step 2 — Add the token to the vault**
+
+```bash
+ansible-vault edit ansible/group_vars/all/vault.yml
+```
+
+Add the key:
+
+```yaml
+gitea_runner_registration_token: "<token-from-step-1>"
+```
+
+**Step 3 — Deploy the runners**
+
+```bash
+ansible-playbook -i ansible/inventory.ini ansible/site.yml \
+  --tags act_runner --ask-vault-pass
+```
+
+Ansible creates `/opt/act_runner/` with a shared `config.yml` and three
+per-runner data directories (`runner-1/`, `runner-2/`, `runner-3/`). On first
+start each container auto-registers with Gitea and writes a `.runner` file to
+its data directory. Subsequent restarts reuse the saved registration.
+
+**Verify**
+
+Back in Gitea **Site Administration → Actions → Runners**, all three runners
+should appear as **Online** within a few seconds.
+
+> **Security note:** Each runner container mounts `/var/run/docker.sock`.
+> This gives workflow jobs root-equivalent access to the host Docker daemon.
+> Only run workflows from trusted repositories.
+
 ## 4. Nextcloud
 
 The admin credentials are set via `nextcloud_admin_user` and