Skip to content

Publishing to GitLab Pages — the pages job, a custom domain and its DNS

The big picture: Your docs site builds in CI and publishes to GitLab Pages. This page explains the mechanics behind that: what the pages job has to look like, the three places a Pages site can be served from, and how to put the site at docs.<project>.<domain> (Blueprint’s own target is docs.blueprint.macrodream.co) with DNS records, a certificate and HTTPS.

Why it matters: Each step is small, but they fail silently and in a fixed order. A domain added in GitLab with no DNS record verifies nothing. A DNS record with no domain added in GitLab returns a 404. A wrong base loads the page and breaks every asset. Knowing what each record is for tells you which one to look at.

How it works: A browser asks your DNS for the name, DNS answers with GitLab’s Pages host, and the GitLab Pages server picks your project’s deployment by matching the Host header against the domains registered under Deploy > Pages. So a custom domain needs two things: it must be registered in GitLab, and it must resolve to GitLab. Two DNS records cover that: one for routing, one to prove you own the name.

Every GitLab behavior below links to GitLab’s documentation, which was read on 2026-10-27. GitLab changes Pages often, so re-check a version number against the linked page before you rely on it.

Blueprint’s own job, from .gitlab-ci.yml:

pages:
stage: deploy
image: alpine:3.23@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
# ci-speed-audit: stage-wait — publishes the site; waits for every lint, test and security job
# No `needs:` on purpose (macrodream/blueprint#288): `needs: ["website:build"]`
# would start this the moment the build finishes, and website:build itself has
# `needs: []`, so the site would publish before lint, tests or the secret scan
# had a verdict. `dependencies:` only limits which artifacts are downloaded.
dependencies: ["website:build"]
# Same guard as website:build: with the site gone neither job exists, and a
# `dependencies:` on a job that is absent would make the whole pipeline invalid.
rules:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
exists:
- website/package.json
script:
- mv website/dist public
artifacts:
paths:
- public

What each part does:

  • The job name and public/. This is the long-standing form: a job named pages whose artifact is a public/ directory. GitLab’s Pages documentation says any job can now deploy Pages if it has the pages property, and that it doesn’t require the job to be named pages. Setting pages: false on a job named pages prevents deployment. The CI/CD YAML reference adds that using pages as a job name is deprecated, and that the content directory needs a non-empty index.html in its root.
  • dependencies: ["website:build"] and mv. The job does not rebuild. It takes the already-built dist/ from website:build and renames it to public/, so the site is built once per pipeline. It uses dependencies:, not needs:, on purpose: website:build starts at once (needs: []), so a needs: on it would publish the site before lint, tests and the security scanners had finished. dependencies: only picks which artifacts to download, and the job still waits for every earlier stage (see why the build is two jobs).
  • rules: on the default branch. Only the default branch publishes, so a feature branch never replaces the live site. The exists: website/package.json clause keeps the job out of the pipeline when website/ has been deleted; a dependencies: entry naming an absent job would make the whole pipeline invalid.
  • artifacts: paths: [public]. The legacy form needs this line, because the artifact is what GitLab publishes.

Per the CI/CD YAML reference:

Feature GitLab version
User-defined job names for Pages (Pages docs) 17.5 behind a feature flag, generally available in 17.6
pages.publish (the publish property moved under the pages keyword; variables allowed) 17.9
pages.publish path appended to artifacts:paths automatically 17.10
pages.expire_in (Premium and Ultimate) 17.4 (variables in 17.11)
pages.path_prefix for parallel deployments (Premium and Ultimate) experiment in 16.7, enabled by default in 17.4, generally available in 17.9; the YAML reference still labels it Beta

With those versions a job can look like this, with no artifacts: block and no mv:

pages:
stage: deploy
dependencies: ["website:build"]
script:
- mv website/dist public # or set pages.publish to website/dist
pages: true

Treat that snippet as a sketch to adapt, not as Blueprint’s job, which uses the long-standing form. If you use pages.publish, check the YAML reference for how it combines with needs: artifacts on your GitLab version.

Parallel deployments publish more than one version of a site, each under its own path. Set pages.path_prefix to something like "mr-$CI_MERGE_REQUEST_IID" in a job that runs on merge request pipelines and every MR gets a URL. They are a Premium and Ultimate feature, and previews expire after 24 hours unless pages.expire_in says otherwise. The number of parallel deployments is capped per top-level namespace. Blueprint does not use them.

Three cases, and base in website/astro.config.mjs must match the one you are in:

Address Served at base
<group>.gitlab.io/<project> (Use unique domain off) a path prefix "/<project>/"
<project>-<hash>.gitlab.io (unique domain, what Blueprint serves from today) the root "/"
A custom domain, such as docs.<project>.<domain> the root "/"

GitLab’s Pages documentation says new projects use unique domains by default, so that projects in a group do not share cookies, and that the unique-domain URL format was shortened in 17.4. The setting is under Deploy > Pages. A wrong base loads the HTML and 404s every asset and internal link, and astro dev hides it unless you test at http://localhost:4321/<base>.

Read the truth from GitLab instead of guessing. The Pages API needs the Maintainer or Owner role:

Terminal window
glab api projects/<group>%2F<project>/pages
glab api projects/<group>%2F<project>/pages_domains

In the first response, url is the address GitLab serves, is_unique_domain_enabled says which of the first two cases you are in, and each entry in deployments carries a path_prefix. The second lists the custom domains registered on the project and their verification state; 404 Not Found means none are registered.

A “vanity” domain is a custom name for the same deployment. It does not move or copy the site: the *.gitlab.io address keeps working, and the custom name is another way in.

This is what makes the name resolve to GitLab. GitLab’s custom domain documentation says:

  • A subdomain such as docs.blueprint.macrodream.co takes a CNAME (or ALIAS) record pointing at your Pages domain, <namespace>.gitlab.io, with no path and no trailing slash. GitLab shows the exact target on the domain’s screen; use that.
  • An apex (the bare macrodream.co) takes A and AAAA records instead. A CNAME at the apex is not recommended, and may fail if the domain also has an MX record. The underlying DNS rule (our explanation, not GitLab’s) is that a name with a CNAME can carry no other record type (RFC 1034 section 3.6.2, RFC 2181 section 10.1), and an apex must carry NS and SOA records. GitLab.com’s addresses on that page are 35.185.44.232 for A and 2600:1901:0:7b8a:: for AAAA; read them from the page again before use, because they have changed before.
  • We recommend a subdomain, because it needs one record, it survives GitLab changing its addresses (a CNAME follows the target; an A record does not), and it leaves the apex free for the marketing site (see section 4).

This is a TXT record GitLab generates for the domain. Without it, anyone could register your domain on their own project and receive your traffic. The record name is _gitlab-pages-verification-code.<domain> and the value is gitlab-pages-verification-code=<code>; copy both from the domain’s screen in GitLab. Some DNS providers append the zone name for you, so enter only the prefix there.

Leave it in place after the domain verifies. GitLab’s documentation says domains are reverified periodically, and that a domain might be turned off if the record is removed. On instances with verification enabled, an unverified domain is removed from the project after 7 days. GitLab.com requires verification.

With Automatic certificate management using Let’s Encrypt on, GitLab obtains and renews a certificate for the domain (Let’s Encrypt integration). GitLab’s documentation says it is turned on and available on GitLab.com; a self-managed administrator must enable it. Issuance can take up to an hour, so HTTPS does not work the moment the domain verifies.

Then turn on Force HTTPS (requires valid certificates) under Deploy > Pages. HTTP requests then get a 301 redirect to HTTPS, and it only works once the certificate exists.

Two DNS constraints from GitLab’s documentation affect issuance:

  • CAA. If the domain or any higher-level domain has a CAA record, it must include letsencrypt.org. Most zones have none, which is fine.
  • One address record. The name needs exactly one CNAME or A record, and no AAAA record when you rely on Let’s Encrypt, per GitLab’s failed-certificate checklist. That conflicts with the apex advice above when GitLab lists an AAAA; another reason to use a subdomain.

If your DNS is on Cloudflare (as in Marketing site on Cloudflare, step 7), create the Pages CNAME and the TXT record as DNS only (grey cloud) first. Our reasoning, not GitLab’s: a proxied (orange cloud) record answers with Cloudflare’s addresses, so GitLab’s checks can no longer see that the name points at it. GitLab’s documentation covers one proxied case: if Cloudflare’s CDN sits in front of Pages, set the SSL connection setting to full rather than flexible. Get the domain verified and the certificate issued with the grey cloud, then decide whether you want the proxy.

The convention is one subdomain per concern, each independent of the others:

  • docs.<project>.<domain> for the docs, from GitLab Pages.
  • The apex (<project>.<domain>, or <domain>) for the marketing site, on another host.
  • Optionally docs-next.<project>.<domain> for pre-release docs, if you publish them.

Each name is its own record set and its own domain registration in GitLab. The GitLab.com settings page lists no wildcard custom domain and caps custom domains at 150 per Pages website. GitLab’s documentation describes no wildcard custom domain on GitLab.com, so plan on adding each name separately.

A self-managed instance can run Pages on a wildcard domain (administration docs), which needs an administrator. Ask the instance owner:

  1. Which Pages domain is configured (it must differ from the GitLab domain), and is a wildcard A record in place for it?
  2. Are custom domains enabled? They need a secondary IP address for the Pages daemon, and a CNAME target that resolves to it.
  3. Which IP should an apex A record use?
  4. Is domain verification on, and is Let’s Encrypt enabled, or must you supply a certificate?

Blueprint’s target is docs.blueprint.macrodream.co, and website/astro.config.mjs already has site: "https://docs.blueprint.macrodream.co" and base: "/".

Not yet registered. Registering the domain with GitLab Pages and creating its DNS records is tracked in issue macrodream/blueprint#291. As of 2026-10-27 the pages_domains call above returns 404 Not Found and the site serves only at the unique-domain address. The record values below are therefore shapes, with the GitLab-generated parts left as placeholders; fill in the real values from GitLab’s domain screen when macrodream/blueprint#291 lands. None of the commands below has been run against the live domain yet.

The records in the macrodream.co zone:

Name Type Value Cloudflare proxy
docs.blueprint CNAME <namespace>.gitlab.io (the target GitLab shows) DNS only
_gitlab-pages-verification-code.docs.blueprint TXT gitlab-pages-verification-code=<code from GitLab> n/a

Steps, in order:

  1. In Deploy > Pages > New Domain, add docs.blueprint.macrodream.co and leave Let’s Encrypt on.
  2. Create the two records above. Wait for DNS, then Retry verification.
  3. When the domain shows verified, wait for the certificate, then turn on Force HTTPS.
  4. Confirm with the commands below.
Terminal window
dig +short CNAME docs.blueprint.macrodream.co
dig +short TXT _gitlab-pages-verification-code.docs.blueprint.macrodream.co
curl -I https://docs.blueprint.macrodream.co/
glab api projects/macrodream%2Fblueprint/pages_domains

What a good result looks like: the first prints the Pages host, the second prints the gitlab-pages-verification-code= value, curl prints HTTP/2 200 with no certificate error, and curl -I http://docs.blueprint.macrodream.co/ prints a 301 to the https:// address once Force HTTPS is on.

Symptom Likely cause What to do
Domain stays unverified The TXT record is missing, has the wrong name (for example the zone name doubled by your DNS provider) or has not propagated dig +short TXT _gitlab-pages-verification-code.<domain>, fix the name, wait (GitLab’s docs say up to 24 hours), then Retry verification
Certificate stays pending Issuance can take up to an hour; or a CAA record excludes Let’s Encrypt; or an extra AAAA record exists Wait an hour, then check the CAA and address records. GitLab’s fix: remove the domain, add and verify it again, and re-enable the toggle
“Something went wrong while obtaining the Let’s Encrypt certificate” Let’s Encrypt could not reach the domain Set Pages visibility to Everyone With Access, retry verification, and check the DNS items in section 3
404 with correct DNS The domain is not added to the project, or not yet verified Add it under Deploy > Pages and check pages_domains
Page loads, assets 404 base does not match where the site is served Compare base with the table in section 2
Browser reports mixed content (our reasoning, not GitLab’s) The page loads an http:// asset, often from a hard-coded site or link Use https:// or relative URLs; set site to the https:// address
Verification or certificate fails behind Cloudflare The record is proxied Set the record to DNS only (grey cloud); if you keep the proxy, set Cloudflare’s SSL mode to full