diff --git a/docs/content/documentation/deployment/gitlab-pages.md b/docs/content/documentation/deployment/gitlab-pages.md index 99ec37c409..f4dc6ade13 100644 --- a/docs/content/documentation/deployment/gitlab-pages.md +++ b/docs/content/documentation/deployment/gitlab-pages.md @@ -3,68 +3,116 @@ title = "GitLab Pages" weight = 40 +++ -We are going to use the GitLab CI runner to automatically publish the site (this CI runner is already included in your repository if you use GitLab.com). +We are going to use the GitLab Runner in GitLab CI/CD to host +the site on GitLab Pages. -## Repository setup +## Configuring your repository -Your repository needs to be set up to be a user or group website. This means the name of the repository has to be in the correct format. +It is possible to host your Zola site on either the SaaS instance offered by +GitLab () or on a self-hosted instance. -For example, assuming that the username is `john`, you have to create a project called `john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`. Once you enable GitLab Pages for your project, your website will be published under `https://john.gitlab.io`. +It is recommended to create a repository on GitLab that contains solely your +Zola project. The [Zola's directory structure](https://www.getzola.org/documentation/getting-started/directory-structure/) +should be located in the root directory of your repository. -Under your group `websites`, you created a project called `websites.gitlab.io`. Your project’s URL will be `https://gitlab.com/websites/websites.gitlab.io`. Once you enable GitLab Pages for your project, your website will be published under `https://websites.gitlab.io`. +For information on how to create and manage a repository on GitLab, refer to: + -This guide assumes that your Zola project is located in the root of your repository. +## Ensuring that the runner can access your theme -## Ensuring that the CI 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. +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. ```bash -$ git submodule add {THEME_URL} themes/{THEME_NAME} +git submodule add {THEME_URL} themes/{THEME_NAME} ``` For example, this could look like: ```bash -$ git submodule add https://github.com/getzola/hyde.git themes/hyde +git submodule add https://github.com/getzola/hyde.git themes/hyde ``` -## Setting up the GitLab CI/CD Runner +## Setting up the GitLab Runner -The second step is to tell the GitLab continuous integration runner how to create the GitLab page. +The GitLab Runner needs to know how to create your site in order to deploy +it to the GitLab Pages server. -To do this, create a file called `.gitlab-ci.yml` in the root directory of your repository. +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. ```yaml -image: alpine:latest +stages: + - deploy + +default: + image: debian:stable-slim + tags: + - docker + variables: - # This variable will ensure that the CI runner pulls in your theme from the submodule - GIT_SUBMODULE_STRATEGY: recursive + # 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: - # Install the zola package from the alpine community repositories - - apk add --update-cache --repository http://dl-cdn.alpinelinux.org/alpine/edge/community/ zola - # Execute zola build - - zola build + - | + 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: - # Path of our artifacts + # 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 - # This config will only publish changes that are pushed on the main branch - only: - - main + 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 ``` -Push this new file and ... Tada! You're done! If you navigate to `settings > pages`, you should be able to see -something like this: +Please, keep in mind that this template assumes you are using the +[Docker executor](https://docs.gitlab.com/runner/executors/docker.html) +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. -> Congratulations! Your pages are served under: -https://john.gitlab.io +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 the process to host on GitLab pages and additional information like using a custom domain is documented -[in this GitLab blog post](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/). +More information on how to host your site on GitLab Pages is available +[in the official GitLab documentation](https://docs.gitlab.com/ee/user/project/pages/).