### Description Git internally uses prefixes for references to distinguish between tags/branches/remotes and so on. ([see docs](https://git-scm.com/book/en/v2/Git-Internals-Git-References)). For example, branch - 'main' and tag - 'v1.0' will be represented as `refs/heads/main` and `refs/tags/v1.0`. But for simplicity `git` can recognize the reference when we provide only the short ref name (`main` or `v1.0`). What if both branch and tag have the same name? ``` > git checkout main warning: refname 'main' is ambiguous. ``` `git` returns a warning when that happens and selects the branch name reference. To select the tag in this case, you have to provide the fully qualified name of the reference. ``` > git checkout refs/tags/main Note: switching to 'refs/tags/main'. ``` ### Problem We support ambiguous references and the same way as `git` allow to use short ref names for them. That causes various problems that introduce the ambiguity to users requests. We introduced `ref_type` option to identify between tags and branches: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122144. That resolves some problems with displaying correct references, but not all of them. ### Proposal [Based on this proposal](https://gitlab.com/gitlab-org/gitlab/-/issues/407184#note_1468087796) The main idea of this approach to prefer commit sha to request resources by references. Why? 1. Commit sha is unique and cannot have a collision inside of the project. 2. Prevention of race conditions. When a user requests `main` branch we emit several requests to build the UI. But what if the pointer to `main` branch is changed between connective requests? We might display a stale data as a result. Usage of commit sha avoids this problem. #### Example The user visits https://gitlab.com/gitlab-org/gitlab page **backend** finds a default branch for the project and exposes both a reference name `main` and a commit sha `aaaa` to **frontend**. **frontend** uses the reference name on UI and the commit sha for API requests.