GitLab Pages not working: 404s, a failing pages:deploy job and broken CSS
Short answer
GitLab Pages publishes a folder of built files, public by default or the one named in pages.publish, from a job named pages or with pages: true; a separate pages:deploy job then deploys it. A 404 usually means there's no index.html at the root of that folder, or the site is at another URL: new projects get a unique domain, such as my-site-123456.gitlab.io, shown under Deploy › Pages. If pages:deploy fails with "missing pages artifacts" or "You need to either include a public/ folder in your artifacts", the job didn't produce that folder. Broken CSS and links on a site without a unique domain usually mean the static site generator's base path isn't set to /project-name/.
The pipeline passes, but the site shows a 404 page, the pages:deploy job fails, or the site loads without its styles. GitLab Pages needs a Pages job, a folder of built files, and an index.html at that folder’s root. Here’s what to check in GitLab 19.5.
A Pages job that works
create-pages:
image: node:22
script:
- npm ci
- npm run build
pages:
publish: dist
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- The job: since GitLab 17.6, any job with
pages: trueor apages:section is a Pages job. Before that, it had to be namedpages. - The folder: Pages publishes
public/unlesspages: publish:names another one, such asdist. Since GitLab 17.10, that folder is added to the job’s artifacts automatically; on older versions, list it underartifacts:paths. - The deploy: after the job, a
pages:deployjob appears in the pipeline. That’s GitLab publishing the files, and it can take a few minutes more before the site is live.
Find the right URL
Go to Deploy › Pages: it lists the active deployment’s URL.
- New projects use a unique domain, such as
https://my-website-123456.gitlab.io/. The older address redirects to it. - With Use unique domain turned off, a project site is at
https://username.gitlab.io/my-website/, or under the group’s name for a group project. - A user or group site comes from a project named
username.gitlab.ioand is served athttps://username.gitlab.io. Group sites must be in a top-level group, not a subgroup.
The site shows 404
- No
index.htmlat the folder’s root. Pages serves only what’s in the published folder. If the build writes todist/but Pages publishes apublic/folder that holds something else, such as your generator’s static files, orindex.htmlsits one folder deeper, the root URL is a 404. Open the Pages job, select Browse under its artifacts, and check what’s really there. - Access control. The Pages setting under Settings › General › Visibility, project features, permissions is Only Project Members by default in private and internal projects. Signed-out visitors are asked to sign in, and signed-in non-members get a 404. Choose Everyone to make the site public.
- An expired deployment. On Premium and Ultimate,
pages: expire_in:stops a deployment after that time, and parallel deployments with apath_prefixexpire after 24 hours by default. Its URL then shows 404, and it’s deleted within minutes: rerun the Pages job, or setexpire_in: never. - Another job replaced it. When several Pages jobs deploy to the same
path_prefix, the last one to finish wins. Limit the Pages job to the default branch, as above.
pages:deploy fails
The pages:deploy job shows why:
- “missing pages artifacts”. The job uploaded nothing. Since GitLab 17.10 the published folder is the job’s artifact, so this usually means the build never created it: check the build’s output folder against
pages: publish:. - “Error: You need to either include a
public/folder in your artifacts, or specify which one to use for Pages usingpublishin.gitlab-ci.yml”. The job uploaded other artifacts, but the published folder is missing or empty. Build intopublic/, or name your build folder withpages: publish:. - “Either the
publishorpages.publishoption may be present in.gitlab-ci.yml, but not both.” Delete the deprecated top-levelpublishand keeppages: publish:. - “artifacts for pages are too large”. The site is over the size limit: 1 GB on GitLab.com, 100 MB by default on GitLab Self-Managed.
- “build SHA is outdated for this ref”. A newer pipeline on the same branch already deployed. Nothing to fix.
Broken CSS, images and links
Without a unique domain, a project site lives under /my-website/, so a link to /assets/app.css points at the domain’s root and 404s. Set your generator’s base path to /my-website/, such as base in Vite and Astro or basePath in Next.js, or keep Use unique domain on so the site is served from the root.
On GitLab Self-Managed, the Pages domain is your instance’s own, not gitlab.io, and an administrator can turn unique domains off by default.
On your phone
MergeBell shows the Pages job’s log live, and Retry reruns a failed job on the free tier. A retry builds the same commit, so a fix to .gitlab-ci.yml or the site needs a new commit. Pages settings, deployments and access control need GitLab in a browser. More in how to retry a failed GitLab pipeline.
Frequently asked questions
Why does my GitLab Pages site show 404?
Most often the published folder has no index.html at its root, for example because the site builds to dist/ while Pages publishes a public/ folder of static files. Other causes: you're at the wrong URL, since new projects use a unique domain listed under Deploy › Pages; Pages access control lets only project members in, the default for private and internal projects; or the deployment expired. Browse the Pages job's artifacts to see what was published.
Why does pages:deploy fail with "missing pages artifacts" or "You need to either include a public/ folder in your artifacts"?
The Pages job finished without the folder Pages publishes: public/ by default. With no other artifacts the message is "missing pages artifacts". Build into public/, or name your build folder with pages: publish: dist in the job. Since GitLab 17.10 that folder is added to the job's artifacts automatically; on older versions, list it under artifacts:paths too.
What is my GitLab Pages URL?
Go to Deploy › Pages in the project: it lists the active deployment's URL. New projects use a unique domain, such as https://my-website-123456.gitlab.io/. With Use unique domain turned off, a project site is at https://username.gitlab.io/project-name/, and a project named username.gitlab.io is served at https://username.gitlab.io.
Why are CSS and JavaScript broken on my GitLab Pages site?
Without a unique domain, a project site lives under /project-name/, so paths that start with / point at the domain's root and 404. Set your static site generator's base path to /project-name/, or keep Use unique domain on so the site is served from the root.
Does the GitLab Pages job have to be called pages?
Not since GitLab 17.6. Any job with pages: true, or a pages: section such as pages: publish: dist, deploys to Pages. On older versions, the job must be named pages.
Sources
- GitLab docs — GitLab Pages
- GitLab docs — GitLab Pages settings and troubleshooting
- GitLab docs — GitLab Pages default domain names
- GitLab docs — pages:publish keyword
- GitLab docs — GitLab Pages access control
- GitLab source — Pages deployment checks (deployment_validations.rb)
Checked against these pages on 8 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.
Do this from your phone with MergeBell
Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.
Get MergeBell for iPhoneGet MergeBell for Android
On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.