GitLab CI template for Zola

This project implements a GitLab CI/CD template to build, test, and analyse your Zola projects.

Usage

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/zola/gitlab-ci-zola@1.0.0
    # 2: set/override component inputs
    inputs:
      # ⚠ this is only an example
      build-args: "build --with-my-args"

Use as a CI/CD template (legacy)

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/zola'
    ref: '1.0.0'
    file: '/templates/gitlab-ci-zola.yml'

variables:
  # 2: set/override template variables
  # ⚠ this is only an example
  ZOLA_BUILD_ARGS: "--minify"

Global configuration

The Zola template uses some global configuration used throughout all jobs.

Input / Variable	Description	Default value
image / ZOLA_IMAGE	The Docker image used to run zola	docker.io/jauderho/zola:latest
site-dir / ZOLA_SITE_DIR	The directory the rendered content will be placed	public
workspace-dir / ZOLA_WORKSPACE_DIR	The directory containing the zola site in the repository	.

Jobs

zola-build job

This job performs build and tests at once.

It uses the following variable:

Input / Variable	Description	Default value
build-args / ZOLA_BUILD_ARGS	Arguments used by the build job	--minify

zola-lint job

This job performs a zola check analysis of your code, mapped to the build stage.

It uses the following variables:

Input / Variable	Description	Default value
lint-disabled / ZOLA_LINT_DISABLED	Set to true to disable the lint analysis	none (enabled)
lint-args / ZOLA_LINT_ARGS	Lint options and arguments	--drafts

zola-lychee job

This job checks links with lychee. It uses the following variable:

Input / Variable	Description	Default value
lychee-enabled / ZOLA_LYCHEE_ENABLED	Set to true to enable this job	none (disabled)
lychee-image / ZOLA_LYCHEE_IMAGE	The Docker image used to run lychee	docker.io/lycheeverse/lychee:latest
lychee-args / ZOLA_LYCHEE_ARGS	lychee arguments to execute	content

Secrets management

Here are some advices about your secrets (variables marked with a ):

1. Manage them as project or group CI/CD variables:
   • masked to prevent them from being inadvertently displayed in your job logs,
   • protected if you want to secure some secrets you don't want everyone in the project to have access to (for instance production secrets).
2. In case a secret contains characters that prevent it from being masked, simply define its value as the Base64 encoded value prefixed with @b64@: it will then be possible to mask it and the template will automatically decode it prior to using it.
3. Don't forget to escape special characters (e.g.: $ -> $$).

Publishing

this template is not a deployment template and it only builds a MkDocs project.

You might deploy the generated site using a GitLab pages job (there is a variant for that) or any other method you see fit.

Variants

GitLab Pages variant

Basically it copies the content of the zola generated site folder (public by default) to the public folder which is published by GitLab pages.

If you wish to use it, Add the following to your .gitlab-ci.yml:

include:
  # main template
  - component: $CI_SERVER_FQDN/to-be-continuous/zola/gitlab-ci-zola@1.0.0
  # GitLab pages variant
  - component: $CI_SERVER_FQDN/to-be-continuous/zola/gitlab-ci-zola-pages@1.0.0