Add .spec.refspec or .spec.ref.customRef to GitRepository

[nashton]

I suggest the following enhancement for the GitRepository API:
Add a field to GitRepository where a git ref[^1] can be specified (.spec.ref.customRef) or a field where a custom git refspec[^2] can be specified (.spec.refspec). This gives a lot more flexibility and would support the following use case:

As a devops engineer, i would like to be able to automatically setup a k8s cluster with flux pointing to the result of a PR merged with destination branch. Most major Git repository hosting services set this PR merge as a custom reference in git, e.g. refs/pull/<PR id>/merge [^3].
Flux only support references on refs/heads/<branch name> or refs/tags/<tag name> using the branch or tag fields, or a commit hash where the commit needs to exist in a tree referenced in the default refspec.

Something to be aware of, if this is to be implemented: I do not know the internals of the git library used, but if it is like the git cli, git clone does not support cloning and checking out a branch not existing in refs/heads/ in one go, even if passing a custom refspec. For example, if wanting to get only the branch refs/pull/1/merge, using git clone -c remote.origin.fetch=+refs/pull/*:refs/remotes/origin/pull/* -b refs/pull/1/merge https://my-git-repo would not work. You would have to do a git init, git remote add origin https://my-git-repo, git fetch origin refs/pull/1/merge --depth 1, git reset --hard FETCH_HEAD

[^1]
Git ref: https://git-scm.com/book/en/v2/Git-Internals-Git-References

[^2]
Git refspec: https://git-scm.com/book/en/v2/Git-Internals-The-Refspec

[^3]
General description of pull request refs, see Pull Request Refs at https://git-scm.com/book/id/v2/GitHub-Maintaining-a-Project
Azure devops: refs/pull/<PR id>/merge
See Build.SourceBranch at https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?l#build-variables-devops-services

Github: refs/pull/<PR id>/merge
See https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally

GitLab: refs/merge-requests/<PR id>/head
See https://docs.gitlab.com/ee/user/project/merge_requests/reviews/index.html#checkout-merge-requests-locally-through-the-head-ref

[nashton]

#1017 ended up being a duplicate, in which the requested feature was added