Docs: Strengthen discoverability of new configuration items

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

• Start this issue's title with Docs: or Docs feedback:.

Problem to solve

• What product or feature(s) affected? GitLab Omnibus package upgrades and configuration management
• What docs or doc section affected?
  • Upgrade documentation: https://docs.gitlab.com/update/upgrade/
  • Package information docs: https://docs.gitlab.com/administration/package_information/#checking-for-newer-configuration-options-on-upgrade
• Is there a problem with a specific document? The gitlab-ctl diff-config tool is documented but not prominently featured in upgrade workflows where administrators need it most
• Any other ideas or requests? Administrators are unaware this tool exists and rely on gitlab-ctl reconfigure to catch deprecated configurations, which it doesn't always do

Further details

• Use cases: Administrators need to know when gitlab.rb template changes occur between versions to ensure their configurations remain current and avoid using deprecated settings
• Benefits: Preventing configuration drift, avoiding deprecated settings, and maintaining best practices
• Audience: System administrators managing GitLab Omnibus installations (persona: Systems Administrator)
• Current gap: Many administrators don't know about gitlab-ctl diff-config until they encounter issues.

Proposal

1. Add a prominent callout in the Omnibus-specific upgrade steps mentioning gitlab-ctl diff-config
2. Consider adding post-upgrade output to gitlab-ctl reconfigure that reminds administrators to run diff-config after major version upgrades
3. Create a dedicated section in upgrade docs for "Omnibus configuration maintenance" that includes:
   • When to use gitlab-ctl diff-config
   • How to interpret the output
   • Best practices for keeping gitlab.rb current
4. Link to this tool from the deprecations/removals sections since configuration changes often accompany feature deprecations

Who can address the issue

• Technical writers familiar with GitLab upgrade documentation
• Omnibus team members who could potentially add the post-upgrade notification to the tooling

Other links/references

• Customer feedback highlighting the issue: Internal support ticket showing administrators are unaware of the tool until encountering configuration conflicts: https://gitlab.zendesk.com/agent/tickets/630434
• Related: The security release monitor provides a good model for how configuration change notifications could work