GitLab Pages CI
Use GitLab 17.10 or newer and a Linux Docker runner to build a Great Docs site. The Pages job publishes the default branch. The merge-request job retains the rendered site as an artefact and leaves the production site unchanged.
Pipeline recipe
Create .gitlab-ci.yml at the package root. This example uses an existing docs/great-docs.yml and installs the package with uv:
.gitlab-ci.yml
.docs-build:
image: python:3.12-bookworm
stage: build
variables:
GIT_DEPTH: "0"
QUARTO_VERSION: "1.11.9"
before_script:
- apt-get update && apt-get install -y --no-install-recommends curl ca-certificates
- |
case "$(uname -m)" in
x86_64) quarto_arch=amd64 ;;
aarch64|arm64) quarto_arch=arm64 ;;
*) echo "Unsupported architecture" >&2; exit 1 ;;
esac
curl --fail --location --output /tmp/quarto.tar.gz "https://github.com/quarto-dev/quarto-cli/releases/download/v${QUARTO_VERSION}/quarto-${QUARTO_VERSION}-linux-${quarto_arch}.tar.gz"
tar -xzf /tmp/quarto.tar.gz -C /opt
ln -s "/opt/quarto-${QUARTO_VERSION}/bin/quarto" /usr/local/bin/quarto
- curl --fail --location --output /tmp/install-uv.sh https://astral.sh/uv/install.sh
- env UV_UNMANAGED_INSTALL=/usr/local/bin sh /tmp/install-uv.sh
- uv venv
- uv pip install -e . great-docs
script:
- uv run --no-sync great-docs build
great-docs-pages:
extends: .docs-build
pages:
publish: docs/_site
rules:
- if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
great-docs-preview:
extends: .docs-build
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
after_script:
- |
if [ "$CI_JOB_STATUS" = success ]; then
uv run --no-sync great-docs ci gitlab-notice --job "$CI_JOB_ID" --mr "$CI_MERGE_REQUEST_IID"
if [ "${GREAT_DOCS_MR_COMMENT:-false}" = true ]; then
uv run --no-sync great-docs ci mr-comment --job "$CI_JOB_ID" --mr "$CI_MERGE_REQUEST_IID"
fi
fi
artifacts:
name: docs-html
paths: [docs/_site]
expire_in: 1 weekThe checked-in gitlab-ci-template.yml asset supplies the same job structure to the setup command. GitLab’s Pages syntax requires a publish path relative to the checkout root and a non-empty index.html. GitLab 17.10 adds that path to the job’s artefacts automatically.
The runner installs Quarto’s Linux tarball and uv’s standalone installer. Change QUARTO_VERSION to select another supported Quarto release. Add system dependencies required by your notebooks to before_script.
Setup command
Generate the pipeline from the selected project’s Python requirement, lock file and output layout:
Terminal
great-docs setup-gitlab-pages
great-docs setup-gitlab-pages --config website/settings.yml
great-docs setup-gitlab-pages --main-branch develop --python-version 3.12
great-docs setup-gitlab-pages --package-manager uvThe command detects uv and Poetry lock files and otherwise installs the package and documentation extras through uv’s pip interface. It uses Python 3.11 or newer and retains an explicit Python-version choice. The default deployment rule reads CI_DEFAULT_BRANCH; --main-branch selects an explicit deployment branch.
If .gitlab-ci.yml already exists, the command prints a snippet for merging and leaves the file intact. Add its jobs to your pipeline and add build to a custom stages list, or change the jobs’ stage to one already present. Use --force to replace the existing file.
Site addresses
During a GitLab CI build, Great Docs uses CI_PAGES_URL when site_url is absent. An explicit site_url wins. An independent seo.canonical.base_url continues to control canonical links. Local project discovery does not infer a GitLab Pages address.
The generated pipeline publishes the selected layout’s final site directory. For website/settings.yml, it publishes website/_site; for an unmigrated root configuration, it publishes great-docs/_site. Versioned builds publish the assembled root, including historical versions under v/.
Deployment check
Commit the reviewed pipeline and run it on your GitLab instance. Open Deploy > Pages to find the deployed address. Verify the homepage, an API page, a nested guide, assets and canonical links, including any URL subdirectory. Inspect the merge-request artefact separately to confirm that its build does not deploy production Pages.
The pipeline and output layout have local coverage. Live Pages deployment acceptance remains pending until those checks run on an authorised GitLab project. The generated pipeline posts no merge-request note by default.
Local previews
Download the documentation archive by its job ID without requiring access to job metadata. Select a pipeline or an MR when metadata access is available:
Terminal
great-docs preview --repo https://gitlab.com/group/package --job 12345
great-docs preview --repo https://gitlab.com/group/package --pipeline 6789
great-docs preview --repo https://gitlab.com/group/package --mr 42
great-docs preview --provider gitlab --repo group/package --mr 42Pass --artifact with the documentation job or archive name when several jobs publish archives. A missing or expired archive needs a new documentation build. GitHub selectors --pr, --run, --branch and --use-gh retain their meanings.
Set GITLAB_TOKEN with read_api access for private artifacts and MR/pipeline metadata. Anonymous access works for public artifacts when the project permits it. A permitted CI_JOB_TOKEN can download job artifacts; it cannot discover pipelines or jobs or post notes. GitLab tokens stay on the GitLab origin during CDN redirects.
For self-managed installations, specify the provider and preserve any HTTP prefix:
Terminal
great-docs preview --provider gitlab \
--repo https://code.example.org/gitlab/team/subteam/package \
--repo-base-url https://code.example.org/gitlab --job 12345Opt-in notes
The generated jobs always print ordinary job-log instructions. Enable sticky MR notes only for trusted pipelines by setting GREAT_DOCS_MR_COMMENT=true and supplying GITLAB_TOKEN with API write permissions and access to the target MR. Keep write credentials out of untrusted contributor builds. A CI job token cannot post notes. Run the note command from a trusted job when contributor code requires isolation.
Terminal
great-docs ci gitlab-notice --job 12345 --mr 42 \
--repo https://gitlab.com/team/package
great-docs ci mr-comment --job 12345 --mr 42 \
--repo https://gitlab.com/team/package \
--artifact-repo https://gitlab.com/contributor/packageUse --repo for the MR target and --artifact-repo for the project that owns the built job. Both share the same instance base. In GitLab CI, the commands use CI_MERGE_REQUEST_PROJECT_URL for the target and CI_PROJECT_URL for the job owner. They derive the base from CI_API_V4_URL unless an explicit configured base is preserved by the generated command. Note lookup follows pagination and updates the existing preview marker; reruns update that note instead of adding another.