# =============================================================================
# Gitea Actions Workflow - Ansible Lint
# =============================================================================
#
# This workflow validates Ansible playbooks and roles using ansible-lint.
# Runs automatically on push and pull request events.
#
# WORKFLOW LOCATION:
#   Gitea Actions requires workflow files in `.gitea/workflows/` directory.
#   This differs from GitHub Actions which uses `.github/workflows/`.
#   See: https://docs.gitea.com/usage/actions/quickstart
#
# RUNNER CONFIGURATION:
#   - `runs-on: ubuntu-latest` matches our runner label from act_runner config
#   - Jobs execute on self-hosted runners registered with this repository's Gitea
#   - Requires runner with `ubuntu-latest:host` label (host execution mode)
#
# WHAT THIS WORKFLOW DOES:
#   1. Checks out the repository code
#   2. Installs uv package manager
#   3. Syncs dependencies from pyproject.toml
#   4. Runs ansible-lint against the playbook
#
# MANUAL TRIGGER:
#   You can manually trigger this workflow from Gitea UI:
#   Repository > Actions > Select workflow > "Run workflow"
#
# DOCUMENTATION:
#   - Gitea Actions: https://docs.gitea.com/usage/actions/overview
#   - Ansible Lint: https://ansible.readthedocs.io/projects/lint/
#   - uv: https://docs.astral.sh/uv/
#   - Workflow Syntax: https://docs.gitea.com/usage/actions/workflow-syntax
#
# =============================================================================

# -----------------------------------------------------------------------------
# Workflow Metadata
# -----------------------------------------------------------------------------

# Human-readable name displayed in Gitea Actions UI.
# Shown in repository's Actions tab and in commit status checks.
name: Ansible Lint

# -----------------------------------------------------------------------------
# Trigger Events
# -----------------------------------------------------------------------------
# Define when this workflow should run.
# See: https://docs.gitea.com/usage/actions/workflow-syntax#on

on:
  # Run on every push to any branch.
  # This catches issues before they're merged.
  push:
    # Optionally limit to specific branches:
    # branches:
    #   - master
    #   - main

  # Run on pull requests targeting any branch.
  # Provides feedback before merge.
  pull_request:
    # Optionally limit to PRs targeting specific branches:
    # branches:
    #   - master
    #   - main

  # Allow manual triggering from Gitea UI.
  # Useful for re-running after fixing external issues (e.g., runner problems).
  workflow_dispatch:

# -----------------------------------------------------------------------------
# Jobs
# -----------------------------------------------------------------------------
# A workflow consists of one or more jobs that run in parallel by default.
# Use `needs:` to create dependencies between jobs if sequential execution
# is required.

jobs:
  # ---------------------------------------------------------------------------
  # Lint Job
  # ---------------------------------------------------------------------------
  # Validates Ansible code quality and best practices.
  lint:
    # Human-readable name shown in Gitea UI for this job.
    name: Ansible Lint Check

    # Runner label to execute this job.
    # Must match a label registered with act_runner.
    # Our runner uses: `ubuntu-latest:host` (see roles/act_runner/defaults/main.yml)
    runs-on: ubuntu-latest

    # -------------------------------------------------------------------------
    # Job Steps
    # -------------------------------------------------------------------------
    # Steps run sequentially within a job.
    # Each step can run commands or use pre-built actions.
    steps:
      # -----------------------------------------------------------------------
      # Step 1: Checkout Repository
      # -----------------------------------------------------------------------
      # Clone the repository to the runner's workspace.
      # Uses the official checkout action maintained by GitHub/Gitea.
      # See: https://github.com/actions/checkout
      - name: Checkout repository
        uses: actions/checkout@v4
        # Default behavior:
        #   - Clones the commit that triggered the workflow
        #   - For PRs, clones the merge commit
        #   - Shallow clone (depth=1) for faster checkout

      # -----------------------------------------------------------------------
      # Step 2: Install uv
      # -----------------------------------------------------------------------
      # Install uv - a fast Python package manager from Astral.
      # Replaces pip/virtualenv with a single, faster tool.
      # See: https://docs.astral.sh/uv/
      - name: Install uv
        uses: astral-sh/setup-uv@v5

      # -----------------------------------------------------------------------
      # Step 3: Sync Dependencies and Run Linter
      # -----------------------------------------------------------------------
      # uv sync reads pyproject.toml and creates a virtual environment
      # with all dependencies (ansible, ansible-lint).
      # uv run executes commands within that environment.
      - name: Run ansible-lint
        run: |
          # Install dependencies from pyproject.toml.
          uv sync

          # Run ansible-lint on the main playbook.
          # Exit code 0 = success (no issues found)
          # Exit code non-zero = linting errors found (fails the workflow)
          #
          # The linter uses .ansible-lint config file for:
          #   - Profile: production (strictest rules)
          #   - Excluded paths: .git/, .gitignore
          #   - Offline mode: true (no network calls)
          uv run ansible-lint playbook.yml