DNS settings

Although you can run a GitLab instance using only IP addresses, using DNS is:

  • Easier for users
  • Required for HTTPS

Depending on the features you want to take advantage of, multiple DNS entries may be necessary. These DNS entries should be one of type:

  • A
  • AAAA

The type depends on the underlying architecture of your instance.

If you don’t want to take advantage of the Let’s Encrypt integration, none of these addresses need to be resolvable over the public internet. Only nodes that will access the GitLab instance need to be able to resolve the addresses.

Adding these entries to your domain’s DNS configuration is entirely dependent on your chosen provider, and out of scope for this document. Consult the documentation from your domain name registrar, hosting provider, or managed DNS provider for the most accurate guidance. Instructions for common DNS registrars include:

It is also possible to utilize dynamic DNS services, such as nip.io, for a quick and easy DNS name for non-production instances. We do not recommend these for any production or long-lived instances, as they are often rate-limited by Let’s Encrypt and insecure. Even if you are successful on initial registration, renewals may subsequently fail.

GitLab Settings

Below is a list of attributes for /etc/gitlab/gitlab.rb that can take advantage of a corresponding DNS entry.

While it is possible to replace the below DNS entries with a wildcard entry in DNS, you still need to provide your GitLab instance with the individual records, and this will not result in the Let’s Encrypt integration fetching a wildcard certificate.


This will be the address that will be used to interact with the main GitLab instance. Cloning over SSH/HTTP/HTTPS will use this address. Accessing the web UI will reference this DNS entry. If you are using a GitLab Runner, it will use this address to talk to the instance.


If you want to use the container registry, this will be an address that is used to interact with the registry. This can also use the same DNS entry as external_url, on a different port. Can be used by the Let’s Encrypt integration.


This is needed if you want to use the bundled Mattermost software. Can be used by the Let’s Encrypt integration.


By default, projects that use GitLab Pages will deploy to a sub-domain of this value.

Auto DevOps domain

If you are going to be deploying projects via Auto DevOps with GitLab, this domain can be used to deploy software. Can be defined at an instance, or cluster level. See the specific documentation for more details.


If you are having issues accessing a particular component, or if Let’s Encrypt integration is failing, you may have a DNS issue. You can use the dig tool to check and verify if DNS is causing you a problem.

Successful DNS query

$ dig registry.gitlab.com

; <<>> DiG 9.10.6 <<>> registry.gitlab.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 12967
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

; EDNS: version: 0, flags:; udp: 1452
;registry.gitlab.com.           IN      A

registry.gitlab.com.    300     IN      A

;; Query time: 56 msec
;; WHEN: Fri Mar 20 14:31:24 CDT 2020
;; MSG SIZE  rcvd: 83

At the least, you are looking for the status to be NOERROR, and theANSWER SECTION for the actual results.

Failed DNS query

$ dig fake.gitlab.com

; <<>> DiG 9.10.6 <<>> fake.gitlab.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 50688
;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 1

; EDNS: version: 0, flags:; udp: 1452
;fake.gitlab.com.               IN      A

gitlab.com.             900     IN      SOA     ns-705.awsdns-24.net. awsdns-hostmaster.amazon.com. 1 7200 900 1209600 86400

;; Query time: 101 msec
;; WHEN: Fri Mar 20 14:51:58 CDT 2020

Notice here, that the status is NXDOMAIN, and there is no ANSWER SECTION. The SERVER field tells you which DNS server was queried for the answer. By default, this is the primary DNS server used by the station the dig command was run from.