Improve developer tooling around URLs in GitLab

Problem

We are inconsistent about how we use URLs (absolute vs relative) in GitLab and it causes a few different problems:

  1. URLs constructed on the frontend that do not take relative_url_root into account break functionality for customers using relative_url_root setting
  2. Some customers have reverse proxies set up where they have a different URL than what was set in the external_url in their gitlab.rb. This means that using absolute URLs does not work.
  3. Geo customers with Secondary site have issues with absolute URLs.

We have some guidance in https://docs.gitlab.com/development/fe_guide/frontend_faq/#5-should-one-use-a-full-url-or-a-full-path-when-referencing-backend-endpoints. But this guidance is hard to find in our docs and there is no tooling to enforce it so there are a lot of instances that slip through the cracks.

Proposal

Standardize web_url and web_path methods on models

  1. Create a new concern that has a web_url and web_path method
  2. Add that concern to all models that are listed in lib/gitlab/url_builder.rb
  3. Remove direct usages of Gitlab::UrlBuilder#build

Make webPath available in APIs

Any API that exposes webUrl should also expose webPath. Search through the following directories:

  • app/graphql/types
  • app/graphql/types
  • /app/serializers
  • /ee/app/serializers
  • /lib/api/entities
  • /ee/lib/api/entities

Linting

  1. Add ESLint rule to prevent webUrl in Vue and JS code. webPath should be used instead.
  2. Add ESLint rule for usages of "/${}" or base: '/'
  3. Add RoboCop rule to prevent usage of *_url in HAML files and controllers (e.g. dashboard_projects_url) and instead use *_path (e.g. dashboard_projects_path)
    • This one could be tricky. I am not sure if we can lint for just Rails URL helpers. Also there may be instances where we need to use *_url (emails?).
  4. Add RoboCop rule for direct usages of Gitlab::UrlBuilder#build.
  5. Add RoboCop rule for APIs that expose webUrl but not webPath

Documentation

Add documentation to the following locations about how to use URLs

Edited by Peter Hegman