github actions: The process /usr/bin/git failed with exit code 128 on checkout
Fixes Actions checkout exit 128 by correcting authentication to the repo: token permissions, persist-credentials, and submodule auth. Not for runner disk or network issues.
TL;DR
Exit 128 on checkout means git could not authenticate to the repository: the GITHUB_TOKEN lacks permission, persist-credentials is off, or submodules need their own auth. Fix the token setup in the checkout step and the clone succeeds.
Error
github actions: The process /usr/bin/git failed with exit code 128 on checkoutSteps
- Read the full log above the 128: git prints the underlying error (authentication failed, repository not found, submodule auth). Expected: the specific git error, not just the exit code.
- Check token permissions: the workflow's
permissionsmust includecontents: readfor the checkout. Expected: the permission is present. - Check
persist-credentials: if a later step needs git auth, keep it enabled; if the checkout itself fails, verify the token input. Expected: the checkout step has a working token. - For submodules in private repos: pass a PAT with access to each submodule repo, or set
submodules: recursivewith the right token. Expected: submodule clones authenticate. - Re-run the workflow. Expected: checkout completes and later steps run.
When to use
- The checkout step fails with git exit 128
- Workflows with private submodules
- After tightening workflow permissions
When not to use
- Runner disk full during checkout (different error)
- Network failures to github.com (connectivity)
Tool compatibility
- GitHub Actions checkout action;
GITHUB_TOKENpermissions, submodule auth
Variant phrasings
checkout fails exit 128 private repo
The token lacks contents: read or the repo moved; check permissions first.
submodule checkout 128 github actions
Submodules need their own auth; pass a PAT covering every submodule repo.
Why it happens
The checkout action is a git client authenticated with the workflow token. Overly tight permissions, disabled credential persistence, or submodules outside the token's reach all surface as git's generic exit 128, hiding the auth detail one line up in the log.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_S8-cHSSgsIeAeQtTAivccw