# git symbolic-ref Command in CI

> git symbolic-ref reads and sets symbolic refs like HEAD. Reference for finding a remote default branch reliably in CI without hardcoding main or master.

Source: https://latchkey.dev/learn/command-reference/git-symbolic-ref-command-reference  
Updated: 2026-06-26

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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git symbolic-ref Command in CI?

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?".

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt