DEV Community

Cover image for GitOps for Homelab DNS (Dnsmasq)
Zepher Ashe
Zepher Ashe

Posted on

GitOps for Homelab DNS (Dnsmasq)

#git #dns #githubactions #automation

Why GitOps?

⚡ It started as a simple typo in /etc/hosts. One wrong hostname. One overlooked IP.

In an instant, my homelab descended into chaos:

  • My Proxmox cluster stopped resolving nodes.
  • The Ceph distributed storage went offline.
  • Every LXC container and VM froze or failed to start.

It was a domino effect: a tiny DNS misconfiguration brought down my entire lab environment.

That’s when I realised: manual DNS editing was a ticking time bomb.

Enter GitOps for DNS - a workflow that stores every host entry in a repo under version control, automates deployment, and ensures a single source of truth.

No more human error. No more cascading failures.

Introduction

In this guide, we’ll implement GitOps-style DNS using dnsmasq, GitHub, Bash, and a cronjob - making your homelab DNS predictable, maintainable, and secure.

Deploy keys (SSH keys) are used to secure repository access, ensuring only your DNS server can pull updates.

🛠 Benefits of a GitOps DNS Workflow

  • 🔄 Automated sync – Changes in Git automatically update the DNS server
  • 🗂 Version-controlled hosts – Every edit is tracked with commit history
  • 🛡 Security-conscious – Deploy keys and configuration validation reduce risk
  • 🧩 Modular & maintainable – Split hosts into .cfg files for easier management
  • ✅ Integrate dnsmasq with GitHub Actions for automated validation

🚀 Installation & Initial Configuration

1. Install dnsmasq and Git 

sudo yum install -y dnsmasq git       # RHEL/CentOS/AlmaLinux
sudo apt install -y dnsmasq git       # Debian/Ubuntu
Enter fullscreen mode Exit fullscreen mode

2. Configure dnsmasq

Create a config file in /etc/dnsmasq.d/:

/etc/dnsmasq.d/000-base.conf

domain=safesploit.com
expand-hosts

log-queries
no-hosts
addn-hosts=/etc/hosts.d

listen-address=172.16.5.27
Enter fullscreen mode Exit fullscreen mode

📝 Tip: Always bind dnsmasq to a specific NIC (listen-address)

⚠️ using 0.0.0.0 is not supported.

Otherwise, dnsmasq will only respond on 127.0.0.1.(

3. Prepare /etc/hosts.d/ (Optional, Modular Setup) 

sudo mkdir -p /etc/hosts.d
sudo touch /etc/hosts.d/000-network.cfg
# sudo touch /etc/hosts.d/XXX-*.cfg  # placeholder files
Enter fullscreen mode Exit fullscreen mode

4. Enable & start service 

sudo systemctl enable dnsmasq
sudo systemctl start dnsmasq
Enter fullscreen mode Exit fullscreen mode

Now dnsmasq is ready to resolve hostnames from /etc/hosts.d/.

5. (Optional) Test after starting dnsmasq

Use dig @<DNS Server IP> <DNS Entry> to query:

dig @172.16.5.27 ldap.safesploit.com +short
Enter fullscreen mode Exit fullscreen mode

This gives proof it works

🖋 Writing Hostnames

Add new .cfg files to /etc/hosts.d/ following a consistent naming scheme like XXX-<subnet_name>.cfg:

  • 005-critical-prod.cfg → critical production hosts
  • 081-mgmt.cfg → management network
  • 100-storage.cfg → storage servers

Example hostnames

Each .cfg file contains simple IP hostname mappings (just like /etc/hosts):

172.16.5.10       ldap
Enter fullscreen mode Exit fullscreen mode 
172.16.100.10      nas1
Enter fullscreen mode Exit fullscreen mode

✅ This modular approach makes it easy to version control, review, and expand.

🔄 GitOps Workflow

Assumed Knowledge: that you already know how to create a GitHub repo.

1. Repository Structure 

.dns-configs/
└── dnsmasq/
    └── hosts.d/
        ├── 005-critical-prod.cfg
        ├── 081-mgmt.cfg
        ├── 100-storage.cfg
        └── XXX-*.cfg
Enter fullscreen mode Exit fullscreen mode

2. Secure Access with Deploy Keys

  • Generate an SSH key for the DNS server: 
ssh-keygen -t ed25519 -f ~/.ssh/id_github_ed25519
Enter fullscreen mode Exit fullscreen mode
  • Add the public key to your GitHub repository’s Deploy Keys with read-only access.
  • GitHub Docs: Managing Deploy Keys

3. Workflow Steps

  • Detect changes on main
  • Clone repo
  • Sync /etc/hosts.d/ via rsync
  • Restart dnsmasq
  • Record applied commit hash

⚠️ Warning: Validate configs before restart:

dnsmasq --test
systemctl restart dnsmasq

🔄 Bash Sync Script & Cronjob

DNS GitOps Script:

⚠️ Make sure you adjust these for your setup

  • REPO="dns-configs"
  • OWNER="github_org/username"
  • GITHUB_DEPLOY_KEY="${HOME}/.ssh/id_github_ed25519"

Bash Script

The script handles:

  • SSH agent setup
  • Change detection via commit hash
  • Cloning and syncing /etc/hosts.d/
  • Restarting dnsmasq
  • Logging and optional quiet mode

Git Clone Bash Script - git_clone_dns_configs_dnsmasq.sh

Cronjob (every 5 minutes): 

*/5 * * * * /root/git_clone_dnsmasq.sh
Enter fullscreen mode Exit fullscreen mode

🔧 Automatic updates reduce errors and maintain consistency.

🔄 (Optional) GitHub Actions CI Validation

At this point, the DNS server can pull host updates from Git.

However, blindly syncing DNS records from Git is risky. A bad hosts entry, duplicate hostname, or broken dnsmasq config could break DNS resolution.

To reduce that risk, I added a GitHub Actions workflow that validates the dnsmasq configuration before changes are accepted.

CI Validation

CI check Reason
Runs inside AlmaLinux 10 Matches the RHEL-style target environment
Installs real dnsmasq service Validates against the actual service
Copies dnsmasq.d and hosts.d Tests realistic file layout
Validates host format Catches malformed records
Detects duplicate hostnames Prevents ambiguous DNS
Creates CI-safe config Avoids binding to homelab-only IPs in CI
Starts dnsmasq on 127.0.0.1:5353 Tests real resolution safely
Uses dig tests Proves records actually resolve

GitHub Actions workflow

GitHub Actions CI Dnsmasq - dnsmasq-ci.yml

Visual DNS Flow 

   [Client Request] 
          |
          v
   [DNS (dnsmasq)]
          |
    ┌─────┴─────┐
    v           v
[Local hosts]  [Upstream DNS]
Enter fullscreen mode Exit fullscreen mode

🖼 Shows decision flow for DNS resolution.

💡 Benefits & Considerations

Benefits:

  • ✅ Version-controlled DNS (rollback capable)
  • ✅ Modular and maintainable
  • ✅ Automatic sync reduces human error
  • ✅ CI/CD guardrails for DNS

Security Notes:

  • 🔑 Protect deploy keys (chmod 600 ~/.ssh/id_github_ed25519)
  • 🔍 Validate dnsmasq configs before restart
  • ⚠️ Be careful with rsync --delete — deletions in Git remove files on server

🔜 Next Steps / Future Improvements

  • ✅ Integrate dnsmasq with GitHub Actions for automated validation
  • ✅ Add linting / syntax checks for host files
  • Support multiple domains or overlay networks
  • Consider BIND migration for more advanced DNS features

Conclusion

GitOps makes your homelab DNS:

  • Predictable – every change tracked
  • Secure – deploy keys and validation
  • Maintainable – modular files and automation

You now have a fully automated, version-controlled DNS workflow for your homelab.

Top comments (0)