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.

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: 35.185.44.232 (the IP address of GitLab Pages on GitLab.com)

If your registrar supports IPv6, also add an AAAA record with the same name and the value 2600:1901:0:7b8a::.

These are the values given by the GitLab Pages documentation for GitLab.com. Remove any other A record on @.

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

Step 4: Configure and verify the domain in GitLab

Now tell GitLab about your domain.

  1. Go to your GitLab project
  2. Click Deploy → Pages (left sidebar)
  3. Click New Domain
  4. Enter your domain name (e.g., mysite.com)
  5. Click Create New Domain

GitLab then shows a verification code: a TXT record that proves the domain is yours. On GitLab.com, the domain doesn't work until it is verified.

  1. At your registrar, add a TXT record:
  2. Name or Hostname: _gitlab-pages-verification-code (some registrars want the full name, _gitlab-pages-verification-code.mysite.com)
  3. Value: the code GitLab shows, which looks like gitlab-pages-verification-code=00112233445566778899aabbccddeeff
  4. Back in Deploy → Pages, click the pencil icon next to your domain, then Retry verification

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 address (35.185.44.232), 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 and the domain is verified, 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 the A record and the TXT verification record are set in your registrar's DNS settings, and that the domain shows as verified in Deploy → Pages 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 and verify it again 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: youruser.gitlab.io (your GitLab namespace, without the project name)

  5. In GitLab, add the domain www.mysite.com as well in Deploy → Pages → New Domain, and add its own TXT verification record (_gitlab-pages-verification-code.www)

  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

The A record already points to GitLab's servers, not to a specific project:

  1. In the old project, go to Deploy → Pages and remove the domain
  2. In the new GitLab project, go to Deploy → Pages → New Domain and add the same domain name

  3. Verify it with the TXT code GitLab shows, as in Step 4

  4. Still stuck? Open an issue on GitHub with steps to reproduce, or ask in the community chat.

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.

To redirect visitors from http://mysite.com (without the s) to https://mysite.com, check Force HTTPS (requires valid certificates) in Deploy → Pages.

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 GitLab's domain (youruser.gitlab.io).

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 GitLab's IP address, 35.185.44.232.

Q2: Besides the A record, what does GitLab.com need before your domain works?

  • A) Nothing else
  • B) A TXT record with the verification code GitLab gives you
  • C) An MX record
Answer

B) A TXT record with the verification code GitLab gives you — on GitLab.com, a domain must be verified. Add the TXT record at your registrar, then click Retry verification in Deploy → Pages.

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 youruser.gitlab.io, and add and verify the www subdomain in GitLab Pages settings
  • C) Contact GitLab support
Answer

B) Add a CNAME record for www pointing to youruser.gitlab.io, and add and verify the www subdomain in GitLab Pages settings — The root domain works with an A record, but www needs a CNAME record and its own domain entry in GitLab.

Edit this page on GitLab