Skip to content
ocx
install

Deploy on GitLab Pages

Render this repository’s CI job file for GitLab, include it from your root .gitlab-ci.yml, then add the pages job GitLab itself requires to publish the built site — ocx-catalog ci renders the build/verify half only; the pages job is yours to write.

Add a ci block to catalog.config.json:

{
"ci": { "forge": "gitlab" }
}

Then run:

Terminal window
npx ocx-catalog ci

This writes .gitlab-ci/catalog.yml — a job file, not a root .gitlab-ci.yml. Add it to your own root file’s include: block, exactly as the rendered file’s own header comment says:

include:
- local: ".gitlab-ci/catalog.yml"

With packageManager defaulted to npm and verifyCi defaulted to true, a first render (no committed pins to carry forward — GitLab jobs pin by image:, not uses:) produces:

# generated by ocx-catalog ci v1 — do not edit
#
# Rendered by `ocx-catalog ci` from this repository's own catalog.config.json
# `ci` block. Not a root .gitlab-ci.yml — this repository's own root file
# includes it:
#
# include:
# - local: ".gitlab-ci/catalog.yml"
#
# Do not hand-edit this file — change the config instead and re-render:
#
# npx ocx-catalog ci
#
# `ci.verifyCi: false` in catalog.config.json omits the catalog:verify job
# below (`ocx-catalog ci --check`) and stops CI from catching a hand-edit —
# the repository then owns this file by hand instead.
catalog:build:
image: node:22-alpine
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
- npm ci
- npx ocx-catalog build
artifacts:
paths:
- dist
catalog:verify:
image: node:22-alpine
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
- npm ci
- npx ocx-catalog ci --check

Both jobs run on a merge request pipeline and on the default branch; catalog:build keeps dist as an artifact, catalog:verify re-renders the job file in memory and fails if it has drifted from catalog.config.json (see CI rendering). Set "verifyCi": false in the ci block to omit catalog:verify.

Set "packageManager": "bun" and the script lines change instead. The image stays node:22-alpine, because the CLI runs on Node 22.13 or later even when bun installs the packages:

image: node:22-alpine
script:
- npm ci
- npx ocx-catalog build

GitLab Pages has its own contract, independent of this package: the publishing job must be literally named pages, and its artifacts must include the directory it publishes — conventionally public. Neither requirement comes from ocx-catalog; add the job yourself in your root .gitlab-ci.yml, alongside the include: block above:

pages:
image: node:22-alpine
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
- npm ci
- npx ocx-catalog build --out dist
- rm -rf public
- mv dist public
artifacts:
paths:
- public

The job builds into dist, clears any checked-in public directory in the job’s throwaway checkout, and moves the result to public, the directory GitLab publishes. Do not pass --out public when your catalog.config.json sets "publicDir": "./public". The build refuses an output that equals or sits inside an input, and fails with OUT_DIR_OVERLAPS_INPUT. The rules: entry limits the job to the default branch. GitLab publishes whatever the most recent successful pages job on that branch produced.

The mirrored /p/* tree also ships an inert _headers file — GitLab Pages never reads it. See Hosting and headers for what that means and what to do about it.