git symbolic-ref Command in CI

git symbolic-ref reads or updates symbolic references, most importantly HEAD.

Scripts that must not assume a branch name use symbolic-ref to discover the actual default branch. It is the robust answer to "is the default main or master here?".

Common flags

HEAD - print the ref HEAD points to (the current branch)
--short - print the short branch name instead of the full refs/heads/... path
refs/remotes/origin/HEAD - read the recorded default branch of the remote
<name> <ref> - set a symbolic ref to point at another ref
--delete <name> / -d - remove a symbolic ref

Example

shell

# Discover the default branch without hardcoding it
DEFAULT="$(git symbolic-ref --short refs/remotes/origin/HEAD | sed 's@^origin/@@')"
echo "default branch: ${DEFAULT}"

In CI

Reading refs/remotes/origin/HEAD with symbolic-ref avoids hardcoding main or master, which makes shared pipeline templates portable across repos. If origin/HEAD is unset, run git remote set-head origin --auto first to populate it.

Key takeaways

git symbolic-ref resolves the real default branch instead of guessing main vs master.
Reading refs/remotes/origin/HEAD makes pipeline templates repo-agnostic.
Populate origin/HEAD with git remote set-head origin --auto if it is missing.