Zensical GitLab CI Component¶

A GitLab CI component for building static sites with zensical and publishing them to GitLab Pages on your default branch.

Features¶

• Simple Zensical Build: Runs zensical build --clean
• Automatic Pages Deploy: Publishes to GitLab Pages from the default branch
• Site/Public Compatibility: Uses public/ directly or renames site/ to public/
• Configurable Job Settings: Customise build and pages job names, stages, and image
• Failure Control: Configure allow_failure separately for build and pages jobs
• Artifact Retention: Keeps generated output artifacts for one week by default

Usage¶

Basic Usage¶

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/zensical/main@latest

stages:
  - build
  - deploy

With Custom Job Names and Stages¶

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/zensical/main@latest
    inputs:
      job_name: "site:build"
      stage: "build-docs"
      pages_job_name: "pages"
      pages_stage: "deploy"

stages:
  - build-docs
  - deploy

The pages job runs automatically only on the default branch:

rules:
  - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

Output Directory Behaviour¶

For GitLab Pages compatibility, the component applies this logic in the pages job:

• If public/ exists, it is used as-is
• If site/ exists and public/ does not, site/ is renamed to public/
• If neither public/ nor site/ exists, the pages job fails

Inputs¶

Main Component (main)¶