You need to sign in or sign up before continuing.

Impossible to Use New Parallel Pages Deployments Without An Existing Pages Deployment

Summary

When attempting to set up parallel deployments for a project on a self-hosted Gitlab instance, one will find it is impossible unless that project already has a deployment of pages without the feature being used.

This is caused because pages:pages.path_prefix cannot be used unless you navigate to "Deploy > Pages" in your project and check the box for the setting pages_multiple_versions_enabled. However, projects that do not yet have a Pages deployment will be redirected to pages/new/ instead where their only option is to fill out the Pipeline Wizard. This creates a cyclic dependency:

In order to access the settings, pages:deploy must run.
In order for a pages:deploy with path_prefix to run, the maintainer must access the settings.

Currently, this Gitlab Pages setting is not exposed via the API, so it's not possible to quickly flip via CLI.

The easiest resolution I've found is to first create MR without pages:pages.path_prefix. This makes a default release to the project's Pages and gives you access to settings. You enable pages_multiple_versions_enabled from there. Then you revise the MR to use the correct prefixes.

Steps to reproduce

Create a new project on a Gitlab instance with the pages_multiple_versions_setting feature flag enabled.
Create a new project with only a README.md file.
In a new branch, define a .gitlab-ci.yml with a pages job that utilizes path_prefix (example included below).
Create a merge request for this branch into the trunk. (Bug encountered here.)
Force merge the branch into the trunk. (Bug encountered here.)

Click to Open - Example CI

stages:
  - deploy

pages:
  stage: deploy
  image: debian:bookworm-slim
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      variables:
        PAGES_PREFIX: docs
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      variables:
        PAGES_PREFIX: docs-${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME}
  script:
    - mkdir public
    - echo "<html><head></head><body>Hi</body></html>" > public/index.html
  artifacts:
    paths:
      - public
  pages:
    path_prefix: $PAGES_PREFIX

What is the current bug behavior?

When the merge request pipeline runs, the final pages:deploy job generated by Gitlab after pages completes will fail. This blocks the merging the MR when successful pipelines are considered a requirement.

If you force this merge request anyway, the subsequent push pipeline on the trunk will also fail in the same way, not generating a pages deployment.

What is the expected correct behavior?

I should be able to access a Project's Gitlab Pages settings without having a pages deployment already created. This would allow me to enable pages_multiple_versions_enabled for the project and both the merge request pipeline and push pipeline would correctly deploy their pages.