We renamed our GitHub organization. Now what?

TL;DR: almost everything keeps working after renaming, just change the remote git URL and check the 3rd party apps that affect your repositories.

A few days ago we decided to finally rename the organization in our GitHub repositories. Quite some time ago, our official company name changed from ”TrustYard“ to ”NejŘemeslníci.cz“ (i.e. to the same name as our web portal) so we wanted our GitHub ”hub“ to match that.

The organization name is part of the remote git URLs to the repositories at GitHub so renaming the org name feels like messing with something really critical. However, is that really so?

It turns out that organization renaming is covered pretty nicely by GitHub. Their help page explains that:

• repository URL requests (such as https://github.com/old_name/repository) will be forwarded to the new organization repo
• but direct organization URL requests (such as https://github.com/old_name) will not get forwarded, they will return a 404 status, and, moreover, may be taken by someone else any time after the renaming.
• all organization-level setup should persist, repositories, teams, installed apps, GitHub actions, 3rd party app access etc…

Seems good! The renaming process itself still feels a bit scary as you need to visit the ”Danger zone“:

But in our case, everything went quite smoothly:

• the procedure was near instant, it didn’t ”take a few minutes“ as we were warned,
• using git with the (now moved) repositories indeed worked without any problems, even without any further changes,
• all GitHub actions seem to have been triggered and reporting correctly,
• other 3rd party apps seem to have been triggered nicely but didn’t report back (see below).

Although the basics work, there are still a couple things to do.

Updating git repository remote URLs

The very straightforward one is to update the remote URLs pointing to your GitHub repositories in all other systems. That typically means your local dev machines, the CI/CD system or your test and production servers.

This step is again nicely described in GitHub help pages. For us, it was all about the following commands:

# find out the remote URL
$ git remote -v
origin  [e-mail]:TrustYard/main.git (fetch)
origin  [e-mail]:TrustYard/main.git (push)

# update the remote URL
$ git remote set-url origin [e-mail]:NejRemeslnici/main.git

# check that the change is applied
$ git remote -v
origin  [e-mail]:NejRemeslnici/main.git (fetch)
origin  [e-mail]:NejRemeslnici/main.git (push)

Do this for all your locally cloned repositories and all systems that work with them. From now on, all your git commands will again communicate with the correct remote repositories, without any redirects.

Updating source code

Now it’s a good time to rename all mentions of the GitHub repositories / organization in the source code. For example, in a Ruby on Rails project deployed via Capistrano, the repo_url configuration item will typically need to be updated.

Another common place to edit in a Rails application might be the Gemfile if you have custom gems managed under your organization (you’d need to run bundle to update the lock-file after changing it).

We also had to update several links to our GitHub wiki pages throughout the source code.

Fixing 3rd party apps

It is common today to have custom apps linked to the GitHub repositories. These are usually the GitHub Actions that seem to overcome the renaming without any issues and other 3rd party apps that might need some attention.

For example, we found that the 3rd party apps were triggered correctly upon pushing to the repositories but were unable to report their status back to the GitHub pull requests. The procedure to fix that will vary a lot among the particular apps, so as an example we’ll show the two of them that we had to fix: SemaphoreCI (our CI pipeline) and our Code coverage tool – codecov.io.

SemaphoreCI

To make SemaphoreCI speak to your repositories again, the Semaphore project repository URL must be updated. At the time of writing, this cannot be done in the admin GUI (the URL input is disabled) but the command-line allows to do this nicely. You need to have the Semaphore CLI installed and configured first. Then, you can update your Semaphore project settings like this:

# get the name of the default project
$ sem get project
NAME   REPOSITORY
nere   [e-mail]:TrustYard/main.git

# update the project settings
$ sem edit project nere
…

The last command opens a text editor with the main project YAML file and here you need to update the repository URL:

…
spec:
  repository:
    url: [e-mail]:NejRemeslnici/main.git
…

After saving that, try re-running a build in SemaphoreCI, it should now report its status back to the corresponding GitHub pull request correctly.

Codecov.io

This 3rd party service was in a similar state: the code coverage builds were properly triggered but the final coverage reports never appeared back among the pull request comments.

For this to start working again we had to go to our account settings in codecov.io and re-visit the GitHub integration via the big black button:

After doing this, codecov started properly reporting to our PRs again.

Conclusion

There is not much to fear about renaming your GitHub organization. Most things work seamlessly and the remaining services need just a little love to successfully resurrect.

Of course, we couldn’t cover all possible services here, so if you have something to say on about renaming org in your particular GitHub setup, we’ll be happy to add it here. Happy refactoring!