Skip to content

hugo-pages

Builds a Hugo site and deploys it to GitLab Pages, mirroring zensical-pages. Two jobs:

  • hugo-build — builds the site to public/. Carries an explicit rules: (when: on_success) so it runs in merge-request pipelines too — a broken Hugo build is caught before merge, not after.
  • pages — deploys the public/ artifact. Runs on deploy_branch and on schedule; never on merge requests. Uses GIT_STRATEGY: none (republishes the artifact, no clone).

Deliberately deploys on schedule

Unlike every other component (which guards schedule → never), hugo-pages deliberately deploys on a pipeline schedule. A nightly rebuild is how future-dated, non-draft posts go live once their date arrives — Hugo excludes future-dated content from production builds until then. The schedule rule sits before the change-detection rules in both jobs, so it can't be gated out by "nothing changed." See Explanation: static sites.

mr_gate: false switches to a "loose" direct-to-main workflow (e.g. a content site audited locally): hugo-build then runs only where it deploys (deploy_branch + schedule), with no MR/branch build — matching a classic Pages-only-on-main setup.

Jobs

Job What it runs
hugo-build hugo --source $[[ inputs.working_directory ]] --destination $CI_PROJECT_DIR/public $[[ inputs.flags ]] --baseURL $[[ inputs.base_url ]]. GIT_DEPTH: 0 feeds enableGitInfo/.Lastmod.
pages Publishes the public/ artifact (pages: true).

Inputs

Input Type Default Description
image string "hugomods/hugo:debian-git-0.163.1" Hugo image. The -git variant bundles git for .GitInfo/.Lastmod; extended debian covers SCSS/Sass themes.
stage string deploy GitLab CI stage (a GitLab default stage — no stages: declaration required).
working_directory string "." Directory containing hugo.toml / the site root.
base_url string "$CI_PAGES_URL/" Value passed to hugo --baseURL.
flags string "--gc --minify" Extra hugo flags. Add --buildFuture to surface future-dated content.
hugo_env string "production" HUGO_ENV. production excludes draft + future-dated content.
tz string "Europe/London" TZ for the build — affects how future-dated content compares against "now".
submodule_strategy string "none" GIT_SUBMODULE_STRATEGY. Set recursive when the theme is a git submodule.
deploy_branch string "main" Branch whose pipelines deploy to Pages.
mr_gate boolean true true = build on MR/branch when content changed (pre-merge gate). false = loose direct-to-main mode.
changes array ["content/**", "layouts/**", "static/**", "assets/**", "themes/**", "data/**", "i18n/**", "config/**", "archetypes/**", "*.toml", ".gitlab-ci.yml"] Change-detection paths for the MR/branch gate and the deploy. The nightly schedule is exempt.

Usage

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]
    inputs:
      submodule_strategy: recursive
      mr_gate: false

See also