👩‍💻 Contributor Guide: Adding a New Ansible Playbook¶

📖 Purpose¶

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

The documentation system enforces a consistent structure, extracts metadata from the playbook itself, and updates all indexes automatically.

---

🛠 Steps to Add a New Playbook¶

1. Create the playbook file ¶

Add your playbook under the playbooks/ directory:

playbooks/my_new_playbook.yml

You may organize playbooks into subfolders:

playbooks/infra/my_new_playbook.yml

Both are supported.

---

2. Add the required Purpose block ¶

Every playbook must begin with a # Purpose: comment.

Example:

# Purpose: Prepares a new VM for Kubernetes workloads.
# Installs container runtime, configures networking, and applies baseline security.
---
- hosts: all
  roles:
    - k8s_node

Guidelines:

• Must appear before any YAML content
• Can span multiple lines
• Drives the global index, folder indexes, and per‑playbook documentation
• If missing, the CI workflow will fail

---

3. Declare roles properly ¶

The documentation generator detects roles via:

• roles: lists
• tasks: entries using ansible.builtin.import_role

Examples:

roles:
  - common
  - { role: firewall }

tasks:
  - name: Include role dynamically
    ansible.builtin.import_role:
      name: k8s_node

These roles will be listed in the generated documentation.

---

4. Commit your changes ¶

Push your branch or open a pull request.

The GitHub Action will automatically:

• Validate the playbook
• Generate documentation
• Update indexes

---

⚙️ What Happens Next¶

The Generate Ansible Playbook Docs GitHub Action runs automatically on push/PR.

It executes:

scripts/generate_playbook_docs.py

The script:

✅ Reads the playbook’s Purpose block
✅ Detects roles used in the playbook
✅ Generates documentation at:

docs/playbooks/<playbook>.md

✅ Updates folder‑level indexes inside:

playbooks/<folder>/README.md

✅ Updates the global index at:

docs/playbooks/README.md

No documentation is written inside the playbook folder itself — only folder‑level indexes remain there.

---

✅ Contributor Expectations¶

• Always include a # Purpose: block at the top of the playbook
• Keep the purpose concise but meaningful
• Declare roles using roles: or import_role
• Organize playbooks into subfolders when appropriate
• Review the PR diff — you’ll see:
  • docs/playbooks/<playbook>.md
  • Updated folder indexes under playbooks/
  • Updated global index under docs/playbooks/README.md

---

🚀 Example¶

After adding:

playbooks/infra/prepare_node.yml

With:

# Purpose: Prepares a VM or baremetal host for Ansible management.
---
- hosts: all
  roles:
    - common
    - ansible_node

The workflow will generate:

• docs/playbooks/prepare_node.md
• Updated playbooks/infra/README.md
• Updated docs/playbooks/README.md

All automatically.

---

✅ Summary¶

Adding a new playbook is simple:

1. Create the playbook under playbooks/
2. Add a # Purpose: block
3. Declare roles
4. Commit and push

The automation handles everything else — documentation, indexing, and consistency.