git symbolic-ref Command in CI

By Daniel Zoghalchali·Latchkey

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.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

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.

Frequently asked questions

git symbolic-ref Command in CI?