How to customize the path where Gitlab Pages are published?

GitLab CI/CD
, ,
1

Problem to solve

Describe your question in as much detail as possible:

  • What are you seeing, and how does that differ from what you expect to see?

    • Gitlab Pages are published to a URL that looks like this: https://<company_name>.gitlab.io/-/<group_name>/product/<other_group_name?>/<project_name>/-/jobs/<job_id>/artifacts/public/index.html
    • I would instead like the URL to look more like this: https://<company_name>.gitlab.io/-/<group_name>/product/<other_group_name?>/<project_name>/<project_internal_version_number>/index.html

In particular, the job_id of the pipeline that generated the docs is not really relevant or important. I would instead want the URL path to mention some internal tracking information, specifically the project version number (which is either available as a git tag, or computed by other means).

  • Consider including screenshots, error messages, and/or other helpful visuals

There are no error messages, but the outcome does not match what I wanted to do, as described above.

Steps to reproduce

Which troubleshooting steps have you already taken? Can you link to any docs or other resources so we know where you have been?

I went through the official documentation and the sub-pages in that section: GitLab Pages | GitLab
I also had a look at the reference projects GitLab Pages examples ยท GitLab, but they also seem to have the <job_id> in their published pages.

Configuration

Add the CI/CD configuration from .gitlab-ci.yml and other configuration if relevant (e.g. docker-compose.yml). Alternatively, create a public GitLab.com example project that provides all necessary files to reproduce the question.

workflow:
  name: Generate and publish the docs
  rules:
    - if: $GIT_SHA_FOR_DOCS
      when: always
    # If we're not provided with a SHA for which the docs are to be built, exit early.
    - when: never

stages:
  - publish

default:
  tags:
    - kubernetes

pages:
  stage: publish
  image: $CI_REGISTRY_IMAGE/docs-builder
    # Note for Gitlab forum post:
    # Above is an internal custom image that contains sphinx and other tools required to perform the build
  variables:
    # We explicitly checkout the specified SHA so there's no need to clone or fetch
    # anything else from the repository.
    GIT_STRATEGY: none
  script:
    - export GRAPHVIZ_DOT=$(which dot)

    - mkdir $CI_PROJECT_NAME && cd $CI_PROJECT_NAME
    - git init && git remote add origin $CI_REPOSITORY_URL
    - git fetch --depth 1 origin $GIT_SHA_FOR_DOCS:refs/remotes/origin/$GIT_SHA_FOR_DOCS
    - git reset --hard remotes/origin/$GIT_SHA_FOR_DOCS

    - make html  # Note for Gitlab forum post: this uses sphinx-build to generate the docs

    # Gitlab Pages expects the docs files to be in a `public` directory at project root.
    - mkdir -p $CI_PROJECT_DIR/public/
    - mv build/html/* $CI_PROJECT_DIR/public/
  artifacts:
    paths:
      - public

Versions

Please select whether options apply, and add the version information.

  • Self-managed
  • GitLab.com SaaS
  • Self-hosted Runners

Versions

  • GitLab (Web: /help or self-managed system information): 16.11.0-pre 67216d888cf
  • GitLab Runner, if self-hosted (Web /admin/runners or CLI gitlab-runner --version): 16.9.0 (656c1943)