Looking for Best Practices for Changing Gitlab Hostname

How to Use GitLab
1

We currently have a production GitLab server at gitlab.example.net (not the real URL) and need to change it to gitlab.example.com to standardize our service URLs.

We are self-hosting GitLab using a Docker container, with all configuration files mounted locally. This setup makes it straightforward to modify gitlab.rb and restart the container, and we can also use the Rails console from inside the container if needed.

My plan is to update gitlab.rb with the new external_url in all the places where it is required and restart the container. This should theoretically update everything. However, since this is our production server, we need to be careful to avoid downtime or unintended issues.

My question is: Are there any other internal configurations in GitLab that could be impacted by this hostname change? Specifically, is there anything beyond updating gitlab.rb that I should be aware of to prevent potential disruptions?

2

Updating/editing gitlab.rb won’t be enough, since any changes applied to it are only activated when running gitlab-ctl reconfigure. that reconfigure command will then fix it in all the places that it needs to be updated.

3

Good to know. Do you know if there could be any required changes with the gitlab-rails console also?

4

The above command is enough to configure everything, nothing else needs to be done in gitlab-rails as the reconfigure command takes care of it all.

5

For a single-server deployment as you describe, this is enough. Also check that the Dockerfile or compose.yaml don’t have the old domain in them.

Do note that all git clones will also need to update their origin remotes for the new URL of the GitLab server.

There’s a tutorial for updating remotes in GitLab’s docs.

You could share that link, and a script like this to all of your developers, so that they can update their remotes:

old_domain="gitlab.example.net"
new_domain="gitlab.example.com"

current_url=$(git remote get-url origin)
new_url=$(echo "$current_url" | sed "s|$old_domain|$new_domain|g")

git remote set-url origin "$new_url"
git remote show origin

(snippet)

For more complicated, multi-server GitLab setups, such as one of the Reference Architectures, then it becomes more involved, particularly if Geo is in the mix, or the old domain is being used for the other servers as well. It would be easiest and least disruptive to create a second instance and migrate to it, but you’d need twice the infrastructure for a short time.

6

We’ve decided to put this plan on hiatus for now because too many of our projects and have the gitlab registry and indiviual files hardcoded with the old hostname. It will be a major undertaking to clean up everything and that would be time not in development for something that really doesn’t matter that much.