GitLab Pages returns 404 error

Hello all,

First off, I could not find a category that looked like it was mostly focused on getting help with GitLab Pages, so picked this category. If I should post this in a different category, please let me know and I will do that.

I am attempting to set up my first ever set of GitLab pages. This effort is on, so the version is the version on the site today. Setting up GitLab Pages for a project looks like it should be a straightforward thing to do. After reading the docs at GitLab Pages and pages_from_scratch and several other places, I created a “.gitlab-ci.yml” file with the following contents:

image: ruby:2.7



  • build
  • test
  • deploy

stage: test
- echo “Testing”
- mkdir “buildit”
- touch “buildit/info.txt”
- test -f “buildit/info.txt”

stage: deploy
- echo “Building and Deploying pages”
- gem install bundler
- bundle install
- bundle exec jekyll build -d public
- public
- if: $CI_COMMIT_BRANCH == “master”

After doing whatever work locally and then committing the changes to the GitLab repository at, a check of files there shows the public directory on GitLab has the html files that should be there and the contents of those html files is correct. Those html files are still there after the CI/CD pipeline runs as expected. However, when I go to Settings -> Pages and click on the link where the GitLab Pages should be found DataCollisions page, I receive a 404 error from GitLab. Changing the setting for this project to be private or public visibility did not resolve the issue, I still get 404 errors. Clearing the browser cache did not resolve the issue either.

I am quite sure I am missing something simple, but I cannot figure it out after 3 or 4 days of reading docs, looking at examples on the GitLab Pages Examples site, and trying everything I can think of.

Any help would be greatly appreciated.

Thanks in advance,


Your website doesn’t have any index.html to serve as default page.
You need to create one!

Meanwhile, you can navigate directly to the files that are on the website, as



Thank you very much for your reply.

Now I am even more confused. You found an example html file for the LICENSE somewhere and provided a link to that file. That link looks a lot like the link in the settings page that should refer to the index.html on the GitLab Pages site DataCollisions Pages Site.
When I add “LICENSE” to the end of that link, I see the html file you found, but when I try “ABOUT” or “INDEX” I see the 404 error again.

I thought all the files for the Pages site were supposed to reside in the /public directory. Presently, there are three html files in the /public directory (index.html, about.html, and license.html) but the version of that license file that you linked to does not match the contents of the license.html file in the /public directory. The /public directory also has the index.html file and an about.html file. So to me, there is a disconnect somewhere because what I see when I look at the files in the /public directory does not look like what I see when I try the link for the site that is presented in the settings page. If I can figure that out, then I think I can fix the site rendering and then continue with the project. Where should I look next to unwind this, and where should the index.html file go if not in the /public directory?

Thanks in advance for your help,


While it’s true that on your repo you have other files in the public directory, while you are running your CI you do a bundle exec jekyll build -d public that replaces the content of your public directory.

To see what is in your website (and the way I found the LICENSE file) is going to the latest pipeline, click on the pages job, and on the right sidebar click on Browse under Job artifacts. There is a better explanation on the Gitlab Docs.

You will see all the files that have been published on your website:

What you have to do now is fixing your Gitlab CI to build the website you want. If you don’t use Jekyll, remove it from the .gitlab-ci.yml and simply copy in public/ the files you want to publish.



Thank you very much for pointing me to what I need to address. I will dive into that and let you know how it works out. Your help is much appreciated!



Hi Ricardo,

Your advice to address the GitLab CI was correct. In the end, I removed the Jekyll instructions from the .gitlab-ci.yml file and then used git push to send the files to the GitLab repository and place the needed files in the /public directory. Once I figured that out, everything works as expected.

Many thanks for your help, I really appreciate that! I also learned something while I was figuring all this out, so thanks for that as well.