Projects · Guides

Ansible role skeleton — walk the public sample

Done: The sample tree is readable, the debug task prints the default message, and the package install stays off.

Requirements

Clone the public skeleton, read every file, and run a local check that does not install a package. This is a skills sample. It is not production Ansible.

• Hardware — any machine with Git and Ansible
• OS — Linux with Ansible 2.14 or newer
• Hostname — localhost for this prove. Do not add a real host inventory to the public mirror.
• Packages — git, ansible-core ≥ 2.14
• Clone — https://www.portfolio.btcbrewery.com/git/ansible-role-skeleton.git (read-only HTTPS)

Variable	Default	What it does
role_skeleton_message	ansible-role-skeleton lab sample	Printed by the debug task
role_skeleton_package	curl	Package name used only when the gate is on
role_skeleton_manage_package	false	When true, Ansible installs that package on the host in inventory

meta/main.yml	Value
role_name	role_skeleton
license	MIT
min_ansible_version	2.14
dependencies	empty

Procedure

Step 1 — Clone the sample

You need the sample tree and Ansible 2.14 or newer before you copy anything. There is no inventory in this mirror.

1. Confirm Ansible meets the minimum.

   ansible --version

   Expected first line contains ansible [core 2.14 or newer.

2. Clone the sample and enter it.

   git clone https://www.portfolio.btcbrewery.com/git/ansible-role-skeleton.git
   cd ansible-role-skeleton
   pwd

   Expected: a path that ends in ansible-role-skeleton.

Step 2 — Walk the tree

Each path has one job. If you cannot point at a file and say what it may change, stop.

1. List the files. Ignore .git.

   find . -type f ! -path './.git/*' | sort

   Expected:

   ./README.md
   ./defaults/main.yml
   ./handlers/main.yml
   ./meta/main.yml
   ./tasks/main.yml
   ./templates/.gitkeep
   ./vars/main.yml

2. Keep this map while you read the next step. defaults/ is what a playbook overrides. vars/ is empty of secrets on purpose. Handlers are a comment, not a service restart you did not ask for.

Step 3 — Read the task and the gate

The debug task always runs. The package task runs only when the gate is true. That flag is not set in defaults/main.yml. The task defaults it to false.

1. Read the defaults.

   cat defaults/main.yml

   Expected:

   ---
   # Lab defaults only — no secrets.
   role_skeleton_package: curl
   role_skeleton_message: "ansible-role-skeleton lab sample"

2. Read the tasks. Confirm the package task has the when gate.

   cat tasks/main.yml

   Expected:

   ---
   - name: Show lab skeleton message
     ansible.builtin.debug:
       msg: "{{ role_skeleton_message }}"
   
   - name: Ensure example package present (lab-safe default)
     ansible.builtin.package:
       name: "{{ role_skeleton_package }}"
       state: present
     when: role_skeleton_manage_package | default(false) | bool

3. Read vars/main.yml and handlers/main.yml. Vars stay empty of secrets. Handlers stay a comment.

   cat vars/main.yml
   cat handlers/main.yml

4. Read the meta. Confirm the role name you will copy in step 4.

   cat meta/main.yml

   Expected: role_name: role_skeleton, license MIT, min_ansible_version: "2.14", dependencies: [].

Step 4 — Syntax-check with the flag off

Check-mode on localhost proves the role without installing a package. Keep the name role_skeleton for this prove. Do not add production hosts.

1. You are still in the clone from step 2. Copy this tree into a local playbook directory.

   mkdir -p "$HOME/lab-ansible/roles"
   cp -a . "$HOME/lab-ansible/roles/role_skeleton"
   cd "$HOME/lab-ansible"
   ls roles/role_skeleton/tasks/main.yml

   Expected: that path exists.

2. Write play.yml pointing at localhost only.

   cat > play.yml <<'EOF'
   - name: Skeleton check
     hosts: localhost
     connection: local
     gather_facts: false
     roles:
       - role: role_skeleton
   EOF

3. Syntax-check. The comma in -i localhost, makes an inventory list. Without it, Ansible looks for a host named localhost in an inventory file you did not write.

   ansible-playbook --syntax-check -i localhost, play.yml

   Expected:

   playbook: play.yml

4. Run check-mode. The package task must stay skipped.

   ansible-playbook -i localhost, play.yml --check

   Expected:

   TASK [role_skeleton : Show lab skeleton message]
   ok: [localhost] => {
       "msg": "ansible-role-skeleton lab sample"
   }
   
   TASK [role_skeleton : Ensure example package present (lab-safe default)]
   skipping: [localhost]

Verification

Syntax-check expected:

playbook: play.yml

Check-mode expected:

TASK [role_skeleton : Show lab skeleton message]
ok: [localhost] => {
    "msg": "ansible-role-skeleton lab sample"
}

TASK [role_skeleton : Ensure example package present (lab-safe default)]
skipping: [localhost]

The package task must stay skipped. Ansible writes no installer log for this check. The play recap is the record.

Next

Rename the role. Replace the message and the package. Keep the when gate until you mean to manage that package. Do not add an inventory of real hosts to this public mirror.

Lab / skills · ansible-role-skeleton · Voice: OWNER-VOICE.md · GUIDE-DESIGN-LAW recut 2026-10-04 · figure: public sample tree