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.
1. The pages CI job
Section titled “1. The pages CI job”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: - publicWhat each part does:
- The job name and
public/. This is the long-standing form: a job namedpageswhose artifact is apublic/directory. GitLab’s Pages documentation says any job can now deploy Pages if it has thepagesproperty, and that it doesn’t require the job to be namedpages. Settingpages: falseon a job namedpagesprevents deployment. The CI/CD YAML reference adds that usingpagesas a job name is deprecated, and that the content directory needs a non-emptyindex.htmlin its root. dependencies: ["website:build"]andmv. The job does not rebuild. It takes the already-builtdist/fromwebsite:buildand renames it topublic/, so the site is built once per pipeline. It usesdependencies:, notneeds:, on purpose:website:buildstarts at once (needs: []), so aneeds: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. Theexists: website/package.jsonclause keeps the job out of the pipeline whenwebsite/has been deleted; adependencies: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.
The newer form
Section titled “The newer form”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: trueTreat 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.
Previews with parallel deployments
Section titled “Previews with parallel deployments”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.
2. Where the site is served from
Section titled “2. Where the site is served from”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:
glab api projects/<group>%2F<project>/pagesglab api projects/<group>%2F<project>/pages_domainsIn 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.
3. How the vanity domain works
Section titled “3. How the vanity domain works”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.
The routing record
Section titled “The routing record”This is what makes the name resolve to GitLab. GitLab’s custom domain documentation says:
- A subdomain such as
docs.blueprint.macrodream.cotakes aCNAME(orALIAS) 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) takesAandAAAArecords instead. ACNAMEat the apex is not recommended, and may fail if the domain also has anMXrecord. The underlying DNS rule (our explanation, not GitLab’s) is that a name with aCNAMEcan carry no other record type (RFC 1034 section 3.6.2, RFC 2181 section 10.1), and an apex must carryNSandSOArecords. GitLab.com’s addresses on that page are35.185.44.232forAand2600:1901:0:7b8a::forAAAA; 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
CNAMEfollows the target; anArecord does not), and it leaves the apex free for the marketing site (see section 4).
The ownership record
Section titled “The ownership record”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.
Certificate and HTTPS
Section titled “Certificate and HTTPS”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 aCAArecord, it must includeletsencrypt.org. Most zones have none, which is fine.- One address record. The name needs exactly one
CNAMEorArecord, and noAAAArecord when you rely on Let’s Encrypt, per GitLab’s failed-certificate checklist. That conflicts with the apex advice above when GitLab lists anAAAA; another reason to use a subdomain.
Cloudflare in front of Pages
Section titled “Cloudflare in front of Pages”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.
4. The docs subdomain naming pattern
Section titled “4. The docs subdomain naming pattern”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:
- Which Pages domain is configured (it must differ from the GitLab domain), and is a
wildcard
Arecord in place for it? - Are custom domains enabled? They need a secondary IP address for the Pages daemon, and a CNAME target that resolves to it.
- Which IP should an apex
Arecord use? - Is domain verification on, and is Let’s Encrypt enabled, or must you supply a certificate?
5. Worked example: Blueprint
Section titled “5. Worked example: Blueprint”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_domainscall above returns404 Not Foundand 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:
- In Deploy > Pages > New Domain, add
docs.blueprint.macrodream.coand leave Let’s Encrypt on. - Create the two records above. Wait for DNS, then Retry verification.
- When the domain shows verified, wait for the certificate, then turn on Force HTTPS.
- Confirm with the commands below.
dig +short CNAME docs.blueprint.macrodream.codig +short TXT _gitlab-pages-verification-code.docs.blueprint.macrodream.cocurl -I https://docs.blueprint.macrodream.co/glab api projects/macrodream%2Fblueprint/pages_domainsWhat 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.
6. Troubleshooting
Section titled “6. Troubleshooting”| 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 |