Keywords: GitLab configuration | URL modification | production deployment
Abstract: This technical article provides a detailed examination of the complete process for securely changing the URL in an operational GitLab environment. Based on a production setup of GitLab v6.0.1, the paper systematically analyzes key configuration file modification points including /etc/hosts, gitlab.yml, gitlab-shell configuration, and Nginx server settings. Special emphasis is placed on considerations for SSL environments, with verification through application status checks and server reboots. The article additionally covers differential configuration methods for Omnibus installations, highlighting that only the external_url parameter in /etc/gitlab/gitlab.rb requires modification followed by reconfiguration commands. Finally, it discusses associated modifications for mail server configurations to ensure proper functioning of system notification features.
Core Configuration Modifications for GitLab URL Changes
Changing the access URL in a deployed GitLab production environment requires systematic modification of multiple critical configuration files. First, new domain resolution records must be added to the operating system's hosts file to ensure proper local network resolution of the new URL. For example, adding an entry like 10.0.0.10 git.domain.com in the /etc/hosts file binds the IP address to the new domain.
GitLab Application Layer Configuration Adjustments
The host parameter in GitLab's main configuration file /home/git/gitlab/config/gitlab.yml must be updated to the new domain. In the production environment, the value of gitlab: host: should be changed to git.domain.com. Simultaneously, the gitlab_url parameter in GitLab Shell's configuration file /home/git/gitlab-shell/config.yml needs to be synchronized, particularly when SSL is enabled, requiring the full HTTPS URL format such as "https://git.domain.com".
Web Server Configuration Updates
Nginx, serving as GitLab's frontend web server, requires modification of the server_name directive in its site configuration file /etc/nginx/sites-available/gitlab to the new domain. Ensure SSL certificate configurations match the new domain to prevent HTTPS connection errors. After modifications, reload the Nginx configuration to activate changes.
Change Verification and System Inspection
Upon completing all configuration modifications, execute GitLab's built-in "Application Status Checks" to validate the status of system components. A server reboot is recommended to ensure all services start with the new configurations. Access the new URL via browser to test core functionalities including repository creation, code commits, and branch operations.
Special Handling for Omnibus Installations
For GitLab installations using Omnibus packages, the URL change process differs. The only file requiring modification is /etc/gitlab/gitlab.rb, where the external_url parameter should be set to the new URL. After modification, execute sudo gitlab-ctl reconfigure and sudo gitlab-ctl restart commands to apply changes. Special attention must be paid to avoid modifying files automatically managed by Omnibus, such as /opt/gitlab/embedded/service/gitlab-rails/config/gitlab.yml, as these files are overwritten during reconfiguration.
Mail Server Configuration Considerations
If the GitLab server also handles email sending functions, review mail-related configurations. In the gitlab.yml file, verify that sender addresses and mail server settings align with the new domain to ensure system notification emails correctly display source information.