Skip to content

Custom domain

Point your own domain (e.g., mysite.com) to your GitLab Pages site. This takes 15 minutes and is free.

By default, your Silex site lives at https://youruser.gitlab.io/projectname/. If you own a domain, you can make visitors go to https://mysite.com instead — and it looks more professional.

What you'll need

  • A domain name (purchased from a registrar like Le Bureau (cooperative), Gandi, or any registrar of your choice)
  • Access to your domain's DNS settings (your registrar's control panel)
  • Your GitLab Pages URL (e.g., https://youruser.gitlab.io/projectname/)

Silex shortcut: You can find your GitLab project link directly in Silex under Site Settings > General tab.

Step 1: Get your GitLab Pages URL

If you don't already know it:

  1. In Silex, open Site Settings > General tab to find your GitLab project link, or go directly to your GitLab project
  2. Click Deploy → Pages (left sidebar)
  3. Under "Access pages at," copy the URL

For example: https://alice.gitlab.io/my-portfolio/

Keep this handy — you'll need it in a moment.

Step 2: Decide between a subdomain or root domain

You have two options:

Option A: Root domain — mysite.com (no www)

This is the simplest for most users. Visitors go to mysite.com and see your site.

Option B: Subdomain — www.mysite.com

Visitors must type www.mysite.com to see your site. mysite.com alone doesn't work unless you set up additional DNS redirects.

This guide covers Option A (root domain). Both are equally valid — choose based on what you prefer and what your registrar supports.

Step 3: Add DNS records at your registrar

This is where it gets technical, but it's just three steps.

Log in to your domain registrar's control panel and find the DNS settings or DNS records section.

You need to add or update an A record:

  • Type: A
  • Name or Hostname: @ (or leave blank — this means the root domain)
  • Value: 185.199.108.153 (this is GitLab's IP address)

GitLab also provides three more IP addresses for redundancy. Best practice is to add all four:

  • 185.199.108.153
  • 185.199.109.153
  • 185.199.110.153
  • 185.199.111.153

How to add them:

Create four separate A records, one for each IP. Set all of them to point to @ (the root domain).

Alternatively, some registrars let you list multiple IPs in a single record. Check your registrar's documentation.

Don't use CNAME for root domains — CNAME records don't work for root domains (only subdomains). Use A records instead.

Step 4: Configure the domain in GitLab

Now tell GitLab about your domain.

  1. Go to your GitLab project
  2. Click Deploy → Pages (left sidebar)
  3. Look for "Domains" section
  4. Click + New domain (or Add domain)
  5. Enter your domain name (e.g., mysite.com)
  6. Click Create domain

GitLab now expects to see those DNS A records pointing to its IP addresses.

Step 5: Wait for DNS propagation

DNS changes don't happen instantly. It typically takes 5 minutes to 24 hours for DNS to propagate worldwide. During this time:

  • Some visitors might see your site, others might see an error or the old site
  • This is normal and temporary

To check if DNS is ready:

  1. Open a terminal or command prompt on your computer
  2. Type: nslookup mysite.com (replace mysite.com with your domain)
  3. If it shows GitLab's IP addresses (185.199.10X.153), DNS has propagated
  4. If it shows something else, DNS hasn't propagated yet — wait and try again in 10 minutes

Alternatively, use an online DNS checker like MXToolbox or DNS Checker.

Step 6: Verify HTTPS (SSL certificate)

Once DNS propagates, your site is live at mysite.com. GitLab automatically provisions a free SSL certificate from Let's Encrypt.

This happens automatically — you don't need to do anything. Look for the lock icon in your browser's address bar. If you see it, HTTPS is working.

If the SSL certificate hasn't appeared yet:

  1. Wait 10 minutes
  2. Go to GitLab → Deploy → Pages
  3. Under your domain, check if there's a "Pending" status
  4. If yes, wait a bit longer. If it stays pending for more than an hour, see troubleshooting below

Troubleshooting

DNS checker shows my records but the site doesn't load

Cause: Your DNS records are set up correctly, but either:

  • DNS hasn't fully propagated (wait 10 minutes and try again)
  • Your browser is caching the old DNS result
  • GitLab Pages hasn't recognized the domain yet

Fix: 1. Open a private/incognito browser window and visit your domain 2. If it works in incognito but not normal, clear your browser cache 3. If it still doesn't work, give DNS another 10-30 minutes to propagate 4. Check your GitLab project's CI/CD pipeline — make sure the latest build succeeded

SSL certificate shows "pending" for more than an hour

Cause: GitLab can't verify that you own the domain, often because DNS wasn't fully configured.

Fix: 1. Double-check that all four A records are set in your registrar's DNS settings 2. Run nslookup mysite.com again to confirm DNS propagation 3. In GitLab, go to Deploy → Pages and remove the domain 4. Wait 5 minutes, then add it again with + New domain 5. Wait another 10-30 minutes for the SSL certificate to be provisioned

"mysite.com" loads but "www.mysite.com" doesn't

Cause: You set up the root domain (@) but not the www subdomain.

Fix:

If you want both mysite.com and www.mysite.com to work:

  1. Add a CNAME record for www:
  2. Type: CNAME
  3. Name or Hostname: www

  4. Value: mysite.com (or your GitLab Pages URL)

  5. In GitLab, add the domain www.mysite.com as well in Deploy → Pages → + New domain

  6. Wait for DNS to propagate

Now both URLs work and show your site.

I want to move my domain to a different GitLab project

You can do this without changing DNS:

  1. In the new GitLab project, go to Deploy → Pages → + New domain
  2. Add the same domain name
  3. In the old project, go to Deploy → Pages and remove the domain
  4. DNS already points to GitLab's servers (not a specific project), so it automatically resolves to the new project

No DNS changes needed.

HTTPS and security

GitLab automatically provides a free HTTPS certificate for your domain via Let's Encrypt. The certificate renews automatically — you don't need to do anything.

HTTPS is enabled by default. If someone visits http://mysite.com (without the s), they're automatically redirected to https://mysite.com.

About A records vs CNAME

  • A record: Points a domain directly to an IP address. Use this for root domains (mysite.com).
  • CNAME record: Points a domain to another domain. Use this for subdomains (www.mysite.com) pointing to the root domain or to GitLab's domain.

GitLab uses A records for root domains because CNAME doesn't work at the root level (DNS standards).

Learn more

Quiz

Q1: What DNS record type should you use for your root domain?

  • A) CNAME
  • B) A record
  • C) MX record
Answer

B) A record — A records point domains to IP addresses. CNAME doesn't work for root domains. Use the four GitLab IP addresses provided.

Q2: How many A records should you add for a root domain?

  • A) One (any of GitLab's IP addresses is fine)
  • B) Four (all of GitLab's IP addresses for redundancy)
  • C) It depends on your registrar
Answer

B) Four (all of GitLab's IP addresses for redundancy) — Adding all four provides better reliability. Most registrars let you add multiple A records pointing to the same domain name.

Q3: How long does it take for DNS changes to take effect?

  • A) Instantly
  • B) 5 minutes
  • C) 5 minutes to 24 hours (typically 10-60 minutes)
Answer

C) 5 minutes to 24 hours (typically 10-60 minutes) — DNS propagation is not instant. It depends on TTL (Time To Live) settings and ISP caching.

Q4: Does GitLab provide HTTPS for your custom domain?

  • A) Only if you pay for an upgrade
  • B) Yes, automatically via Let's Encrypt
  • C) You must install your own SSL certificate
Answer

B) Yes, automatically via Let's Encrypt — GitLab provisions and renews free HTTPS certificates automatically. No action needed on your part.

Q5: If you want both mysite.com and www.mysite.com to work, what extra step is needed?

  • A) Nothing, both work automatically with A records
  • B) Add a CNAME record for www pointing to your root domain, and add the www subdomain in GitLab Pages settings
  • C) Contact GitLab support
Answer

B) Add a CNAME record for www pointing to your root domain, and add the www subdomain in GitLab Pages settings — The root domain works with A records, but www needs a CNAME record pointing to the root domain.

Edit this page on GitLab