Host your website for free with GitLab Pages (step-by-step)

No Comments
Published: 05.06.2022

Do you want to learn how to host your next website for free with GitLab Pages? In this post, you will learn what is required to host your site, and then I will show you step-by-step how to do so!

In this post, we will cover the following topics:

Server icon

VPS Hosting Course

Learn everything you need to know about servers and hosting your own applications!

What are GitLab Pages?

GitLab Pages is a static site hosting service provided by GitLab. It uses HTML, CSS, and JavaScript inside a repository to publish your website to the web! The coolest thing… all of this is completely free of charge. Meaning you can use GitLab Pages to host the landing page of your next project or the complete project (depending on the type) on the web for free!

Overall this works similar to GitHub Pages that you can use to host repositories that you created on GitHub! If you use GitHub, this post here is better suited for you.

Some questions regarding GitLab Pages

What can you host with GitLab Pages and what not?

You can use GitLab Pages to host every type of static site. That means that the website is delivered to the user exactly as you defined it with HTML, CSS, and JavaScript.

Need help or want to share feedback? Join my discord community!

On the other hand, you cant use GitLab Pages to host applications that require server-side technologies (like express js) to run.

How is the URL of your final site structured?


If this guide is helpful to you and you like what I do, please support me with a coffee!

The basic URL structure is:

One exception is the URL structure for a repository named like The resulting URL is:

Can you use a custom domain?

Yes! Check the detailed guide provided by GitLab here.

What state does the repository have to be in?

The repository can either be public, private, or internal.

How to host a free website with GitLab Pages?

Compared to other options, GitLab Pages does not offer a simple way to host your free website through a web UI. Instead, you have to set up a CI that generates the page for you and gets executed in specific situations. So, for the step-by-step guide, let’s start with your project in the editor of your choice (you can also use the Web IDE).

For this example, we will use the website that we created with VITE and Tailwind CSS in this blog post here. (I recreated the GitHub repo on GitLab to show it in this post.)

  1. Create a file called .gitlab-ci.yml with the following contents (hint: read the comments to see what you might need and whatnot):
image: node:16.5.0
  stage: deploy
        - package-lock.json
      prefix: npm
      - node_modules/
    # needed for the vite build step only
    - npm install
    - npm run build
    # the final contents for your page always have to be stored in the public folder
    - cp -a dist/. public/
    # artifact to make it visible for gitlab pages
      - public
  1. Commit and push the new file
  2. Visit your free website under the suitable domain we discussed in the last section (for me it is


In this post, we learned how to use GitLab to host a static website for free. You can use this to host the landing page of your next big project, or in some cases, you can even host the whole project.

I think it is a bit sad that GitLab does not offer a web interface to create your free pages. Other providers like GitHub offer this functionality and lower the barriers to a free website for everyone with it. Nonetheless, if you have some experience with CI, it works pretty easily, and luckily GitLab offers a lot of templates to ease that process.

Did you use GitLab Pages already? Share your experience in the comments below!

If you got some questions regarding this post or anything else regarding your projects, feel free to ask! I would love to help you 🙂

And lastly, if you liked this blog post, consider subscribing to my newsletter. In it I send a monthly update on all the posts I created!

Discussion (0)

Add Comment

Your email address will not be published. Required fields are marked *