zola/docs/content/documentation/deployment/gitlab-pages.md

+++ title = "GitLab Pages" weight = 40 +++

We are going to use the GitLab Runner in GitLab CI/CD to host the site on GitLab Pages.

Configuring your repository

It is possible to host your Zola site on either the SaaS instance offered by GitLab (https://gitlab.com) or on a self-hosted instance.

It is recommended to create a repository on GitLab that contains solely your Zola project. The Zola's directory structure should be located in the root directory of your repository.

For information on how to create and manage a repository on GitLab, refer to:

https://docs.gitlab.com/ee/user/project/repository/

Ensuring that the runner can access your theme

Depending on how you added your theme, your repository may not contain it. The best way to ensure that the theme will be added is to use submodules. When doing this, ensure that you are using the https version of the URL.

git submodule add {THEME_URL} themes/{THEME_NAME}

For example, this could look like:

git submodule add https://github.com/getzola/hyde.git themes/hyde

Setting up the GitLab Runner

The GitLab Runner needs to know how to create your site in order to deploy it to the GitLab Pages server.

We provide you with a template to accomplish this task easily. Create a file called .gitlab-ci.yml in the root directory of your repository and copy the contents of the template below.

stages:
  - deploy

default:
  image: debian:stable-slim

variables:
  # The runner will be able to pull your Zola theme when the strategy is
  # set to "recursive".
  GIT_SUBMODULE_STRATEGY: "recursive"

  # If you don't set a version here, your site will be built with the latest
  # version of Zola available in GitHub releases.
  # Use the semver (x.y.z) format to specify a version. For example: "0.17.2" or "0.18.0".
  ZOLA_VERSION:
    description: "The version of Zola used to build the site."
    value: ""

pages:
  stage: deploy
  script:
    - |
      apt-get update --assume-yes && apt-get install --assume-yes --no-install-recommends wget ca-certificates
      if [ $ZOLA_VERSION ]; then
        zola_url="https://github.com/getzola/zola/releases/download/v$ZOLA_VERSION/zola-v$ZOLA_VERSION-x86_64-unknown-linux-gnu.tar.gz"
        if ! wget --quiet --spider $zola_url; then
          echo "A Zola release with the specified version could not be found.";
          exit 1;
        fi
      else
        github_api_url="https://api.github.com/repos/getzola/zola/releases/latest"
        zola_url=$(
          wget --output-document - $github_api_url |
          grep "browser_download_url.*linux-gnu.tar.gz" |
          cut --delimiter : --fields 2,3 |
          tr --delete "\" "
        )
      fi
      wget $zola_url
      tar -xzf *.tar.gz
      ./zola build      

  artifacts:
    paths:
      # This is the directory whose contents will be deployed to the GitLab Pages
      # server.
      # GitLab Pages expects a directory with this name by default.
      - public

  rules:
    # This rule makes it so that your website is published and updated only when
    # you push to the default branch of your repository (e.g. "master" or "main").
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Please, keep in mind that this template assumes you are using the Docker executor on your GitLab Runner. Feel free to adjust the file to your workflow and specific requirements.

After you push this file to the default branch of your repository (e.g. "master" or "main"), your site will be ready. The GitLab CI/CD pipelines will ensure your site is published and updated automatically.

On the left sidebar of GitLab, navigate to Deploy > Pages to find the URL of your website inside the Access pages section.

More information on how to host your site on GitLab Pages is available in the official GitLab documentation.