Initial commit: Ansible playbook for Gitea Act Runner deployment

Automated deployment of act_runner on Ubuntu 20.04+ servers:
- Docker CE installation (DEB822 format)
- Node.js 24.x via NodeSource
- act_runner binary with SHA256 verification
- systemd service with security hardening
- CI: ansible-lint via Gitea Actions

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

playbook.yml

@@ -0,0 +1,97 @@
+---
+# =============================================================================
+# Gitea Act Runner - Deployment Playbook
+# =============================================================================
+#
+# This playbook deploys and configures Gitea Act Runner on Ubuntu servers.
+#
+# USAGE:
+#   # Standard deployment (interactive vault password prompt):
+#   ansible-playbook -i inventory/hosts.yml playbook.yml --ask-vault-pass
+#
+#   # Dry run (preview changes without applying):
+#   ansible-playbook -i inventory/hosts.yml playbook.yml --check --diff --ask-vault-pass
+#
+#   # Deploy to specific hosts only:
+#   ansible-playbook -i inventory/hosts.yml playbook.yml --limit runner-01 --ask-vault-pass
+#
+# PREREQUISITES:
+#   - Ansible 2.15+ on control machine
+#   - SSH access to target servers (root or sudo user)
+#   - Vault password for encrypted secrets (group_vars/vault.yml)
+#   - Target servers running Ubuntu 20.04 or later
+#
+# WHAT THIS PLAYBOOK DOES:
+#   1. Validates target OS is supported (Ubuntu 20.04+)
+#   2. Updates apt package cache
+#   3. Installs Docker CE
+#   4. Installs Node.js LTS via NodeSource
+#   5. Downloads and installs act_runner binary
+#   6. Creates act_runner system user
+#   7. Deploys configuration and registers with Gitea
+#   8. Sets up systemd service for automatic startup
+#   9. Verifies all components are working
+#
+# DOCUMENTATION:
+#   - Gitea Actions: https://docs.gitea.com/usage/actions/overview
+#   - Act Runner: https://docs.gitea.com/usage/actions/act-runner
+#   - Ansible: https://docs.ansible.com/ansible/latest/
+#
+# =============================================================================
+
+- name: Deploy Gitea Act Runner
+  hosts: all
+  become: true
+  gather_facts: true
+
+  # ---------------------------------------------------------------------------
+  # Pre-tasks: Validation and preparation before role execution
+  # ---------------------------------------------------------------------------
+  pre_tasks:
+    # Fail early if the target OS is not supported.
+    # This prevents confusing errors later in the playbook.
+    - name: Validate target operating system
+      ansible.builtin.assert:
+        that:
+          - ansible_facts['distribution'] == "Ubuntu"
+          - ansible_facts['distribution_major_version'] | int >= 20
+        fail_msg: >-
+          This playbook requires Ubuntu 20.04 or later.
+          Detected: {{ ansible_facts['distribution'] }} {{ ansible_facts['distribution_version'] }}
+        success_msg: >-
+          Target OS validated: {{ ansible_facts['distribution'] }} {{ ansible_facts['distribution_version'] }}
+
+    # Update apt cache before installing packages.
+    # cache_valid_time prevents unnecessary updates on repeated runs.
+    - name: Update apt package cache
+      ansible.builtin.apt:
+        update_cache: true
+        cache_valid_time: 3600  # Skip update if cache is less than 1 hour old
+
+  # ---------------------------------------------------------------------------
+  # Roles: Main installation logic
+  # ---------------------------------------------------------------------------
+  roles:
+    - role: act_runner
+      tags:
+        - act_runner
+
+  # ---------------------------------------------------------------------------
+  # Post-tasks: Summary and verification
+  # ---------------------------------------------------------------------------
+  post_tasks:
+    # Display deployment summary for operator confirmation.
+    # Uses variables registered during verification tasks.
+    - name: Display deployment summary
+      ansible.builtin.debug:
+        msg:
+          - "=============================================="
+          - "Gitea Act Runner - Deployment Complete"
+          - "=============================================="
+          - "Runner name: {{ act_runner_name }}"
+          - "Gitea instance: {{ gitea_instance_url }}"
+          - "Service status: {{ 'RUNNING' if act_runner_service_status.status.ActiveState == 'active' else 'NOT RUNNING' }}"
+          - ""
+          - "Verify in Gitea UI:"
+          - "  {{ gitea_instance_url }}/-/admin/actions/runners"
+          - "=============================================="