## Problem I recently attempted to set up badges for my project and [discovered](https://gitlab.com/gitlab-org/gitlab/-/issues/22278) 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](https://docs.gitlab.com/ee/api/project_badges.html#add-a-badge-to-a-project), I encounter the following error: ```bash $ 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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/155804#note_2080118753). ## 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](http://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.