mirror of https://github.com/getzola/zola
117 lines
3.9 KiB
Markdown
117 lines
3.9 KiB
Markdown
+++
|
|
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](https://www.getzola.org/documentation/getting-started/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.
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
## 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.
|
|
|
|
```yaml
|
|
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](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.
|
|
|
|
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](https://docs.gitlab.com/ee/user/project/pages/).
|