Skip to main content

GitLab Pages CI

Build documentation for merge requests and publish the default branch with GitLab Pages.

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 week

The 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 uv

The 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 42

Pass --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 12345

Opt-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/package

Use --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.