Unclear usage of `%{gitlab_server}` and `%{gitlab_pages_domain}` badge placeholder

Problem

I recently attempted to set up badges for my project and discovered the %{gitlab_server} and %{gitlab_pages_domain} placeholders. However, their usage isn't clear from the documentation, as it appears I can't use them as hostnames in the image or link URLs.

A common use case for a link URL is pointing to a file in the project's repository or a page on GitLab Pages.

When attempting to use %{gitlab_server} or %{gitlab_pages_domain} with the REST API, I encounter the following error:

$ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
	--data-urlencode "link_url=https://%{gitlab_server}/%{project_path}/commits/main" \
	--data-urlencode "image_url=https://shields.io/my/badge1" \
	--data-urlencode "name=mybadge" \
	"https://gitlab.com/api/v4/projects/:id/badges"
{"message":{"link_url":["is blocked: URI is invalid"]}}	

It appears that %{gitlab_server} and %{gitlab_pages_domain} cannot be used as hostnames in the base URLs of link_url or image_url, but only as parameters. This limitation is currently undocumented (admittedly, all examples have the hostname hardcoded and don't use these placeholders either) and feels counterintuitive. A similar comment has been made here.

Proposal

If this behavior is intentional, I suggest:

• Documenting where the %{gitlab_server} and %{gitlab_pages_domain} placeholders can be used, with special emphasis on this limitation.

Alternatively:

• Allow using %{gitlab_server} and %{gitlab_pages_domain} as part of the base URL for links and images
• Consider adding %{project_web_url}, %{gitlab_server_url}, and %{gitlab_pages_url} shortcuts to make badge usage more robust. These would enable the following use cases:
  • Use a shortcut to point to a file in the project, independent of the instance URL (e.g., when migrating projects between GitLab instances): %{project_web_url}/-/blob/%{default_branch}/LICENSE
  • Use a shortcut to point to another project in the same group: %{gitlab_server_url}/%{project_namespace}/gitlab-profile/-/blob/main/README.md
  • Use a shortcut to point to a page on GitLab Pages: %{gitlab_pages_url}/index.html
• Modify the URL validation to allow using placeholders in the base URL

An additional error appears to have been fixed recently, which I still encounter on our self-hosted 17.2.2 instance but cannot reproduce on gitlab.com. When editing an existing badge using the Web UI and using %{gitlab_server} and %{gitlab_pages_domain} in the scenario described above, no error was shown about an invalid URL. Instead, the dialog simply closed without changing the URL after clicking the "Save changes" button.