How to Deploy a Site with GitLab Pages (Step-by-Step Guide)

Introduction

GitLab Pages is GitLab’s free hosting service for static websites. If you use GitLab for your repositories, you can publish your site directly from a branch using GitLab CI/CD.

This guide will show you how to host a simple static website on GitLab Pages.

Why Use GitLab Pages?

• Free hosting with GitLab
• Custom domains + HTTPS
• Perfect if you already use GitLab for your code
• Deploys automatically when you push changes

Step 1: Create a GitLab Repository

1. Sign in to GitLab.com.
2. Create a new repository.
3. Upload your website files (index.html, CSS, JS).

Step 2: Add a .gitlab-ci.yml File

In the root of your repo, create a file named .gitlab-ci.yml with this content for static sites:

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
  artifacts:
    paths:
      - .public
  only:
    - main

This tells GitLab to copy your site files into a .public folder and deploy them.

Step 3: Push to GitLab

Commit and push your changes:

git add .
git commit -m "Setup GitLab Pages"
git push origin main

Step 4: Wait for Deployment

GitLab CI/CD will run the job. When it finishes, your site will be available at:

https://your-username.gitlab.io/your-project

Step 5: Add a Custom Domain (Optional)

1. Go to your project → Settings → Pages.
2. Add your custom domain.
3. Update your DNS records to point to GitLab’s servers.

Troubleshooting

• CI/CD job failed? Double-check .gitlab-ci.yml syntax.
• Missing index.html? Ensure you have an index.html in the root.
• Custom domain not working? Check DNS settings and allow time for propagation.

Conclusion

GitLab Pages is a solid free option if you already keep your code on GitLab. With a simple .gitlab-ci.yml, you can deploy static websites quickly and securely.

Up next in Hosting Academy: we’ll look at Heroku, a platform for deploying full-stack and backend apps.