Skip to content

Recent changes in GitLab routing

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

This is "For Your Information" issue. Treat it as a lightweight alternative to a blog post.

Since we created the GitLab subgroups feature, we introduced more complexity to routing within the GitLab application.

Let's say you visit URL like https://gitlab.com/gitlab-org/gitlab-foss. In this particular case, GitLab sees that you request gitlab-foss project page within gitlab-org group. By identifying group and project name, routing can run a corresponding piece of code and render a correct page to end user.

Things become more complex with subgroups. Let's use the same URL as before. With subgroups feature, gitlab-foss can be project or a subgroup. We must query the database to find out if gitlab-foss is a project or a subgroup so we can show user a correct page.

It becomes even trickier when we include page name in it. For example this URL: https://gitlab.com/gitlab-org/creator-pairing/issues. Is it issues project within creator-pairing subgroup? Or simply issues page within creator-pairing project?

To make routing job easier we introduced a special separator almost 2 years ago. If you visit cluster page for your project now, you will see that URL looks like this: https://gitlab.com/gitlab-org/gitlab-foss/-/issues. Now, by having /-/, we know exactly where group or project name ends and page name starts.

Here are few examples:

https://gitlab.com/gitlab-org/gitlab
                      |          |
                   group      project

https://gitlab.com/gitlab-org/gitlab/-/blob/master/Gemfile
                      |         |             |                       
                    group     project        page 

https://gitlab.com/gitlab-org/creator-pairing/rails-app/issues
                      |           |              |          |
                   group        subgroup      subgroup    project

https://gitlab.com/gitlab-org/creator-pairing/rails-app/-/issues
                      |           |              |           |
                   group      subgroup       project       page

Why we do it

There are several reasons to use the special separator:

  1. Performance. The Separator helps to speed up things up, which processes the URL the better.
  2. Stability. Separator allows for more predictable and reliable routing, which means less bugs.
  3. Simplicity. It's much easier to build a new routing when you know its unlikely to conflict with an existing one.

How it affects our users

For the last two years we are slowly moving all existing routes to use this /-/ separator. During every release, we converted more and more pages to use the new format. By 12.9 we adopted the new routing system for most of the pages . We are trying to make ease the inconvenience so we will have redirects and support for old URLs for a period of time. Every major release we are going to do a cleanup and remove old deprecated routes.

Some URL's will stay longer than others. For example issue, merge request, and raw pages:

https://gitlab.com/gitlab-org/gitlab/raw/master/Gemfile
https://gitlab.com/gitlab-org/gitlab/issues/123
https://gitlab.com/gitlab-org/gitlab/merge_requests/123

Some will be gone soon. Like:

https://gitlab.com/gitlab-org/gitlab/branches
https://gitlab.com/gitlab-org/gitlab/deploy_keys
https://gitlab.com/gitlab-org/gitlab/settings

For most URLS, you are likely already using the new URL format. If you did not notice the change then we did everything right. If you did, we are sorry for the inconvenience. Feel free to share your experience with us.

P.S. Thanks Sean for suggesting this blog post idea.

Further read

If you are interested in details and progress on this subject you can take a look at following issues:

Edited by 🤖 GitLab Bot 🤖