Documentation for

Ansible Quick-Start: Install, Deploy Pi-hole, and Add GitLab CI Lint (Homelab Automation)

Ansible Resources

🖥️ Example Environment: Admin workstation + Debian 12 server

Pre‑Install

sudo apt update
sudo apt install pipx git sshpass -y
pipx install --include-deps ansible
pipx install --include-deps ansible-lint
pipx ensurepath

To enable pipx command autocompletion, run: pipx completions

Example for bash: eval "$(register-python-argcomplete pipx)"

Verify installation:

ansible --version

Clone Your GitLab Repo

git clone https://<your-gitlab-url>/ansible.git
cd ansible

Install a Community Role from Ansible Galaxy

Create requirements.yml

nano requirements.yml

---
# HSE cloudflared role
- src: HomeSecExplorer.cloudflared
# HSE PiHole role
- src: HomeSecExplorer.pihole

Install the role:

ansible-galaxy install -r requirements.yml -p roles/

Directory tree now looks like:

ansible/
└── roles/
    ├── HomeSecExplorer.cloudflared/
    └── HomeSecExplorer.pihole/

Write the Playbook

nano playbook.yml

Sample content:

---
- name: My ansible playbook
  hosts: all
  become: true
  tasks:
    - name: Install PiHole and DOH proxy
      ansible.builtin.include_role:
        name: "{{ item }}"
      loop:
        - "HomeSecExplorer.cloudflared"
        - "HomeSecExplorer.pihole"
      vars:
        hseph_pw_plain: "Passw0rd"  # change role defaults variable
      when: "'dns' in group_names"  # only run on inventory group dns

Create inventory

nano hosts

[dns]  # host group
pihole1 ansible_host=10.10.10.196

Test Syntax

ansible-lint playbook.yml

Run the Playbook

Connect to host once and accept the ssh key

ansible-playbook -i hosts playbook.yml -u <ssh_user> -k -K

Options explained:

-i: Specifies the inventory file.
-u: SSH user for connecting to the target host(s). Can also be set in the inventory.
-k: Prompt for the SSH password. Optional if using key-based auth or setting password in the inventory.
-K: Prompt for the sudo password (become password). Can also be set via inventory.

Once run, you should see tasks from the Pi-hole role being executed.

You can now test with dig @10.10.10.196 google.com

Add GitLab CI Lint Pipeline

Create .gitlab-ci.yml:

nano .gitlab-ci.yml

stages:
  - lint

ansible-lint:
  stage: lint
  image: registry.gitlab.com/pipeline-components/ansible-lint:latest
  script:
    - ansible-lint

Create gitignore file

We don’t need to push downloaded roles, so add them to .gitignore:

nano .gitignore

roles/

Commit & Push

git add .
git commit -m "My commit"
git push

GitLab CI requires an available runner. Check GitLab → CI/CD → Pipelines for a green check-mark ✅.

Next Steps

Expand inventory to multiple hosts
Secure variables with Ansible Vault
Integrate GitLab CI for full deployment

FilesExpand file tree

BasicAnsible.md

Latest commit

History