git config --global: Usage, Options & Common CI Errors
git config --global writes settings that apply to every repo for the current user.
CI jobs lean on global config to set a bot identity, default branch, and the safe.directory exceptions that newer Git requires inside containers.
What it does
git config --global reads and writes the per-user config file (~/.gitconfig or $XDG_CONFIG_HOME/git/config), affecting all repositories run by that user.
Common usage
git config --global user.name "CI Bot"
git config --global user.email "ci@example.com"
git config --global init.defaultBranch main
git config --global --add safe.directory /workspace
git config --global --listOptions
| Flag | What it does |
|---|---|
| --global | Use the per-user config file |
| --add <key> <value> | Append a multi-valued key |
| --get <key> | Read a value |
| --unset <key> | Remove a value |
| --list | Show all effective settings |
Common errors in CI
fatal: detected dubious ownership in repository at ‘<dir>’ - the checkout is owned by a different uid than the running user (common with Docker). Fix with git config --global --add safe.directory <dir>. If $HOME is unset, --global has nowhere to write; export HOME or use --file.
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.
- 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