---
# =============================================================================
# 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"
          - "=============================================="