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.
Render the CI job file
Section titled “Render the CI job file”Add a ci block to catalog.config.json:
{ "ci": { "forge": "gitlab" }}Then run:
npx ocx-catalog ciThis 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 --checkBoth 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-alpinescript: - npm ci - npx ocx-catalog buildimage: node:22-alpinescript: - npm install -g bun@1 - bun install --frozen-lockfile - bun x ocx-catalog buildAdd the pages job
Section titled “Add the pages job”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: - publicThe 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.