ai-instructions: Instructions file for GitHub Copilot

Ansible Role Governance

Dependencies

• For task-execution conventions (idempotency, variable passing, and changed_when/failed_when keys), defer to ansible-playbook-style.instructions.md.
• For playbook and task naming conventions, see ansible-playbook-style.instructions.md.

Naming Conventions

• Name role directories with lowercase snake_case.
• Name role task files with lowercase kebab-case or snake_case.
• Use one casing convention consistently within each role.
• Name variable keys with lowercase snake_case.

Rules

Directory ownership

• Keep each role self-contained with tasks, vars, handlers, templates, files, and meta directories as needed.
• Keep tasks/main.yml as the role entry point that orchestrates internal task files.
• Keep template rendering in templates/*.j2 and static artifacts in files/.
• Keep OS-specific task trees under tasks/<os_family>/ (for example tasks/debian/, tasks/ol9/, tasks/windows/).
• Keep reusable cross-role utilities as importable task files in a dedicated common role.
• Declare role dependencies and Galaxy collection requirements in meta/main.yml with required fields: role_name and namespace.

Role Metadata (meta/main.yml)

• Required structure:

  ---
  galaxy_info:
    role_name: my_role        # lowercase, no hyphens; uniquely identifies role
    namespace: my_namespace   # lowercase; must match ^[a-z][a-z0-9_-]+$ (no dots)
    author: Author Name
    description: "Role description"
    license: MIT              # required field
    min_ansible_version: "2.10"  # required field; optional fields (tags, github_branch, etc.) below per ansible-galaxy requirements
  

• Namespace values must match ^[a-z][a-z0-9_-]+$.
• Do not use dot-separated namespace values (for example, local.proxmox).
• Run ansible-lint to validate meta/main.yml for Galaxy compliance before marking role complete.
• Do not assume default role name from directory; always explicitly declare role_name and namespace.