👩‍💻 Contributor Guide: Adding a New Ansible Role

📖 Purpose

This guide explains how to add a new Ansible role to the homelab repository and ensure its documentation is automatically generated by our GitHub Action workflow.

🛠 Steps to Add a New Role

1. Create the role folder
   • Add a new directory under roles/ with your role name:

     roles/my_new_role/
     

2. Add required files
   • At minimum, include:
     • meta/main.yml → defines role metadata (name, description, author, license, supported platforms, dependencies).
     • tasks/main.yml → defines tasks for the role.
     • defaults/main.yml → optional, for default variables.
     • vars/main.yml → optional, for constant variables.
     • handlers/main.yml → optional, for handlers.
3. Fill in metadata
   • Example meta/main.yml:

     galaxy_info:
       role_name: my_new_role
       author: Your Name
       description: Short description of what this role does.
       license: MIT
       min_ansible_version: "2.9"
       platforms:
         - name: Ubuntu
           versions:
             - focal
             - jammy
     dependencies: []
     

4. Commit your changes
   • Push your branch or open a pull request.

⚙️ What Happens Next

• The Generate Ansible Role Docs GitHub Action runs automatically on push/PR.
• It executes scripts/generate_role_docs.py, which:
  • Reads your meta/main.yml, defaults, vars, tasks, and handlers.
  • Generates a README.md inside your role folder.
  • Updates the central roles/README.md index with a link to your role.

✅ Contributor Expectations

• No manual README writing needed → the script handles it.
• Keep metadata accurate → description, platforms, and dependencies drive the docs.
• Use comments in variable files → they appear in the generated tables.
• Check the PR diff → you’ll see your role’s README and the index updated automatically.

🚀 Example

After adding roles/my_new_role/ and pushing, you’ll see:

• roles/my_new_role/README.md → auto-generated documentation.
• roles/README.md → updated index entry:

📑 meta/main.yml Starter Template

galaxy_info:
  role_name: my_new_role
  author: Your Name
  description: >
    Short description of what this role does.
    (Keep it concise but clear for auto-generated docs.)
  license: MIT
  min_ansible_version: "2.9"

  platforms:
    - name: Ubuntu
      versions:
        - focal
        - jammy
    - name: EL
      versions:
        - "7"
        - "8"

# List other roles this one depends on.
# These will be documented automatically in the README.
dependencies: []

🔑 Key Fields Explained

• role_name → Must match the folder name under roles/.
• author → Contributor’s name or team.
• description → Appears in the generated README and central index.
• license → License type (MIT, GPL, etc.).
• min_ansible_version → Minimum version required for the role.
• platforms → OS families and versions supported.
• dependencies → Other roles that must run before this one.

🚀 Contributor Tip

• Keep descriptions short but meaningful — they show up in the role index.
• Add dependencies if your role relies on another (e.g., common, firewall).
• Update platforms whenever you test against new OS versions.