Consolidate GitLab Pages configuration options definition in docs/omnibus/charts
Right now we duplicate descriptions of all the configuration options for GitLab Pages in multiple places:
- In pages flags descriptions: https://gitlab.com/gitlab-org/gitlab-pages/-/blob/189eeedc91148c9c217374d9292bba740a1f801c/internal/config/flags.go#L30-L30, (Ideally, this should be SSOT, as it's where we modify defaults/descriptions in the first place)
- docs https://docs.gitlab.com/ee/administration/pages/#global-settings
- omnibus
gitlab.rb
template https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/6885feb06d90c85f327571e151e78e7c1d30f6e8/files/gitlab-config-template/gitlab.rb.template#L1618 - charts docs: https://gitlab.com/gitlab-org/charts/gitlab/-/blob/d0dfe88ff70cf62af858ea8cdce038f821697660/doc/charts/gitlab/gitlab-pages/index.md
This leads to a few different problems:
- there are actually a lot of discrepancies amount these files. Some settings are missing in docs/omnibus/charts
- some default values are not documented in docs/omnibus/charts
- it's really hard to maintain docs: developers need to modify it in 4 different places. It's probably ok when it comes adding new options, but when you just want to change the default or flag description, you need to do a lot of unnecessary busywork.
- it's harder for users to find docs. E.g. if you are reading our main docs https://docs.gitlab.com/ee/administration/pages/#global-settings, it's not obvious how these options are translated to charts
So I suggest:
-
audit https://docs.gitlab.com/ee/administration/pages/#global-settings, make sure it has all the settings from https://gitlab.com/gitlab-org/gitlab-pages/-/blob/189eeedc91148c9c217374d9292bba740a1f801c/internal/config/flags.go#L30-L30 -
add a column GitLab Pages chart option name
-
move all options that just passed to pages daemon from https://gitlab.com/gitlab-org/charts/gitlab/-/blob/d0dfe88ff70cf62af858ea8cdce038f821697660/doc/charts/gitlab/gitlab-pages/index.md to https://docs.gitlab.com/ee/administration/pages/#global-settings, (Note: some options will be not obviously named like gitlabCache.cleanup
instead ofgitlabCacheCleanup
) -
In omnibus( gitlab.rb
template) and charts just direct users to https://docs.gitlab.com/ee/administration/pages/#global-settings -
Optionally: add a default column to https://docs.gitlab.com/ee/administration/pages/#global-settings, it maybe useful for users, but it will make it a bit harder to maintain
This way https://docs.gitlab.com/ee/administration/pages/ will become a single source of truth, and it will be easier to maintain.
Edited by Vladimir Shushlin