Skip to content

Using dnsmasq to dynamically handle GitLab Pages subdomains

You can use dnsmasq to test GitLab Pages sites locally without having to configure each site on /etc/hosts.

Use dnsmasq on macOS

To use dnsmasq on macOS:

  1. Install dnsmasq:
brew install dnsmasq
  1. Set up the *.test domain lookup:
# Ensure the configuration directory exists
mkdir -p $(brew --prefix)/etc/

# Add `*.test` to the `127.0.0.1` lookup
echo 'address=/.test/127.0.0.1' >> $(brew --prefix)/etc/dnsmasq.conf

# Start `dnsmasq`
sudo brew services start dnsmasq
  1. Create a DNS resolver:
# Ensure the resolver directory exists
sudo mkdir -p /etc/resolver

# Add the localhost address as a resolver for `.test` domains
echo "nameserver 127.0.0.1" | sudo tee /etc/resolver/test

You can now create a GitLab Pages site locally with a dynamic domain. If you configure GitLab Pages and create a root/html project, that project is accessible through http://root.gdk.pages.test:3010/html.

Troubleshooting

For GitLab Runner, you must define gdk.test in /etc/hosts. If you're using GitLab Runner locally, you must also configure /etc/hosts:

# Append GDK configuration in `/etc/hosts`
cat <<-EOF | sudo tee -a /etc/hosts

## GDK
127.0.0.1  gdk.test
::1        gdk.test
# ----------------------------
EOF