Skip to content

Deploy a docs site

Two components deploy a static site to GitLab Pages — zensical-pages for a Zensical microsite, hugo-pages for a Hugo site. Read Explanation: static sites for the design reasoning; this page is the setup steps. This very site is built by zensical-pages — its self-include lives in this repo's own root .gitlab-ci.yml, so you're looking at a live example right now.

Zensical site

stages:
  - pages

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]

Requirements in your repo:

  • zensical.toml at working_directory (repo root by default).
  • A docs/ directory (or whatever docs_path points at) with your Markdown content.
  • A requirements-lock.txt (or whatever python_lock points at) — a pip-compile-style lockfile that includes zensical.

For a monorepo where docs live somewhere other than the repo root:

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]
    inputs:
      working_directory: "apps/docs"
      changes:
        - "apps/docs/**/*"
        - ".gitlab-ci.yml"

Remember to narrow changes to match — the default assumes docs at the repo root, and a too-broad filter for a monorepo means unrelated changes elsewhere trigger a docs rebuild for nothing (not incorrect, just wasted runner time).

Hugo site

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]

Requirements in your repo:

  • hugo.toml (or your Hugo config) at working_directory.
  • If your theme is a git submodule, set submodule_strategy: recursive — otherwise the theme won't be checked out and the build fails.

For a site with time-bound content — posts that should go live on a future date — no extra configuration is needed; the schedule-based deploy that publishes them is on by default. What you do need is a pipeline schedule configured in your project (Settings → CI/CD → Pipeline schedules) so there's actually a nightly trigger for hugo-pages to deploy on. Without one, future-dated content never goes live on its own — see Explanation: static sites for why this is deliberate, not a workaround.

For a "loose" workflow — content audited locally, no MR build gate wanted:

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

Verify

Open an MR that touches your docs content. For Zensical, or for Hugo with the default mr_gate: true, the build job should run and you can download its public/ artifact to preview locally. Merge to your default branch — the pages job deploys, and your site should be live at your project's Pages URL within a minute or two.

See also