Pages custom_domain_mode not applied

Summary

When configuring GitLab Pages on Omnibus GitLab with a dedicated NGINX (pages_nginx['enable'] = true), the documented setting gitlab_pages['custom_domain_mode'] is not applied to gitlab.yml by gitlab-ctl reconfigure. As a result, administrators cannot enable Pages custom domains via gitlab.rb as documented, and must resort to manual edits to gitlab.yml after each reconfigure.

This was reported by a self-managed Premium customer on Omnibus GitLab 18.5.1, and confirmed by Support.

Current behavior

Given a configuration like:

# /etc/gitlab/gitlab.rb

pages_external_url 'https://pages.example.com'

pages_nginx['enable'] = true          # dedicated NGINX for Pages (used for Pages auth)
gitlab_pages['enable'] = true
gitlab_pages['external_http'] = []    # traffic goes via NGINX
gitlab_pages['custom_domain_mode'] = 'http'

After:

sudo gitlab-ctl reconfigure

the generated /var/opt/gitlab/gitlab-rails/etc/gitlab.yml does not contain custom_domain_mode under the pages: configuration:

pages:
  enabled: true
  # custom_domain_mode: http   # ← missing, despite being set in gitlab.rb

Effects:

  • Custom domains for Pages remain disabled in the UI (“Support for domains and certificates is disabled…”).
  • Setting gitlab_pages['custom_domain_mode'] = 'http' in gitlab.rb has no effect on gitlab.yml.

If an administrator instead manually edits /var/opt/gitlab/gitlab-rails/etc/gitlab.yml and adds:

pages:
  enabled: true
  custom_domain_mode: http

then custom domains work as expected until the next gitlab-ctl reconfigure, which overwrites the manual change.

Expected behavior

  • When gitlab_pages['custom_domain_mode'] is set in gitlab.rb, Omnibus should:

    1. Render the corresponding pages.custom_domain_mode entry in gitlab.yml during gitlab-ctl reconfigure.
    2. Preserve this behavior across subsequent reconfigures and upgrades, without requiring manual edits to gitlab.yml.

  • This should work when pages_nginx['enable'] = true, which is currently the recommended/supported way (for the affected customer) to enable Pages authentication via the dedicated NGINX proxy.

Workaround

The current workaround is:

  1. Run gitlab-ctl reconfigure as usual.

  2. Manually edit /var/opt/gitlab/gitlab-rails/etc/gitlab.yml and add:

    pages:
  enabled: true
  custom_domain_mode: http

  3. Restart Rails components:

    sudo gitlab-ctl restart puma
sudo gitlab-ctl restart sidekiq

Limitations:

  • The manual change is overwritten on every gitlab-ctl reconfigure (including upgrades and other config changes), so it must be re-applied each time.
  • The customer wants to avoid any configuration changes outside of Omnibus and manage the instance exclusively via gitlab.rb and gitlab-ctl reconfigure.

Impact

  • A self-managed Premium customer (Omnibus 18.5.1) using Pages with authentication via pages_nginx['enable'] = true cannot reliably enable Pages custom domains using the documented gitlab_pages['custom_domain_mode'] setting.

  • The documentation currently describes this setting as supported in gitlab.rb, but Omnibus does not apply it, leading to:

    • Confusing behavior and extended troubleshooting.
    • Fragile operational workarounds (manual gitlab.yml edits).
    • Reluctance to change infrastructure (e.g., disabling pages_nginx or introducing a secondary IP) just to work around this gap.

Suspected root cause / historical context

  • The gitlab_pages['custom_domain_mode'] integration appears to have been introduced and then reverted:

  • From a self-managed Omnibus perspective:

    • The docs describe gitlab_pages['custom_domain_mode'] as a valid setting.
    • The Omnibus code path that maps this to pages.custom_domain_mode in gitlab.yml is missing after the revert.

Proposal

  1. Clarify intended support surface

    • Confirm whether gitlab_pages['custom_domain_mode'] is intended to be supported for self-managed Omnibus installations, especially with pages_nginx['enable'] = true.

  2. If supported (preferred)

    • Re-introduce or re-implement the mapping from gitlab_pages['custom_domain_mode'] in gitlab.rb to pages.custom_domain_mode in gitlab.yml.
    • Ensure it behaves correctly in at least these configurations:
      • pages_nginx['enable'] = true (dedicated NGINX, Pages auth).
      • pages_nginx['enable'] = false with gitlab_pages['external_http']/external_https.
    • Add tests to cover these scenarios and avoid regressions like the prior revert.

  3. If not supported (for now)

    • Explicitly document that gitlab_pages['custom_domain_mode'] is not applied by Omnibus and is currently unsupported for self-managed Omnibus.
    • Optionally, have gitlab-ctl reconfigure emit a clear warning when gitlab_pages['custom_domain_mode'] is set but ignored, to avoid silent misconfiguration.

Environment details (from affected deployment)

  • GitLab edition: Self-managed Premium
  • Install type: Omnibus (Linux package)
  • GitLab version: 18.5.1
  • Pages configuration (high level):
    • pages_nginx['enable'] = true (dedicated NGINX, used for Pages auth)
    • gitlab_pages['enable'] = true
    • gitlab_pages['custom_domain_mode'] = 'http' (currently ignored by Omnibus)
  • Source: Internal GitLab Support ticket referencing this behavior (self-managed Omnibus customer)

2. GitLab docs issue draft

Project: gitlab-org/gitlab
Suggested labels:

  • Category:Pages
  • documentation
  • type::bug
  • customer

Summary

The GitLab Pages administration documentation describes gitlab_pages['custom_domain_mode'] as a supported Omnibus configuration option, but on Omnibus GitLab 18.5.1 this setting is ignored by gitlab-ctl reconfigure when pages_nginx['enable'] = true.

This mismatch between documentation and actual behavior caused confusion for a self-managed Premium customer and required Support to recommend a fragile manual workaround.

Current documentation behavior

On the GitLab Pages admin docs page (for example, in the “Custom domains” section), the docs:

  • Mention gitlab_pages['custom_domain_mode'] as a valid configuration option in gitlab.rb.
  • Do not state any limitation around:
    • Omnibus support for this setting, or
    • Interactions with pages_nginx['enable'] = true (dedicated NGINX / Pages auth setups).

Based on this documentation, administrators expect that adding:

gitlab_pages['custom_domain_mode'] = 'http'

to gitlab.rb will result in the equivalent pages.custom_domain_mode entry in gitlab.yml, enabling custom domains.

Actual behavior on Omnibus

On a self-managed Omnibus instance (18.5.1) with:

pages_nginx['enable'] = true
gitlab_pages['enable'] = true
gitlab_pages['custom_domain_mode'] = 'http'

Support confirmed that:

  • gitlab-ctl reconfigure does not write custom_domain_mode into /var/opt/gitlab/gitlab-rails/etc/gitlab.yml.

  • Custom domains remain disabled in the UI.

  • The only way to enable custom domains is to manually edit gitlab.yml after each reconfigure and add:

    pages:
  enabled: true
  custom_domain_mode: http

This is operationally unsafe (changes are overwritten on each reconfigure) and contradicts the documentation’s implication that gitlab_pages['custom_domain_mode'] is supported for Omnibus.

Related implementation history:

Net result: the documentation describes a setting that is not currently wired up in Omnibus.

Impact

  • Self-managed Omnibus administrators may:

    • Spend time troubleshooting why gitlab_pages['custom_domain_mode'] “does nothing”.
    • Implement risky manual workarounds (editing gitlab.yml after each reconfigure).
    • Potentially avoid otherwise-desirable topologies (e.g., keeping pages_nginx['enable'] = true for authentication) due to unclear support status.

  • Support needs to repeatedly explain that the documented configuration is not actually honored by Omnibus in these versions/setups.

Proposal

Short-term (docs fix)

Until the Omnibus behavior is clarified or fixed (see related Omnibus issue):

  1. Update the GitLab Pages administration docs section that describes gitlab_pages['custom_domain_mode'] to clearly state:

    • This setting is not currently applied by the Omnibus GitLab package in versions where the Omnibus MR was reverted.
    • On Omnibus, setting gitlab_pages['custom_domain_mode'] in gitlab.rb will not populate pages.custom_domain_mode in gitlab.yml.
    • As a result, enabling Pages custom domains in Omnibus with pages_nginx['enable'] = true is not supported via this setting at the moment.

  2. Optionally, add:

    • A note that there is an open Omnibus issue tracking implementation of this setting for self-managed Omnibus (link to the new omnibus-gitlab issue once created).
    • A warning against manual edits to gitlab.yml as a long-term solution (these edits are overwritten on reconfigure and should be treated as a last-resort workaround).

Longer-term (once Omnibus behavior is decided)

  • When Omnibus implements or re-enables support for gitlab_pages['custom_domain_mode'], update the docs again to:

    • Specify the minimum GitLab version where it works for Omnibus.
    • Clarify any constraints (e.g., behavior with pages_nginx['enable'] = true vs false, required network topology, etc.).
    • Remove or revise any warnings about the setting being ignored.

References