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