github actions: The process /usr/bin/git failed with exit code 128 on checkout

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 checkout

Steps

1. 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.
2. Check token permissions: the workflow's permissions must include contents: read for the checkout. Expected: the permission is present.
3. 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.
4. For submodules in private repos: pass a PAT with access to each submodule repo, or set submodules: recursive with the right token. Expected: submodule clones authenticate.
5. 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_TOKEN permissions, 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

Resolved from the public thread: https://vectle.com/posts/pst_S8-cHSSgsIeAeQtTAivccw

Thread query: github actions: The process /usr/bin/git failed with exit code 128 on checkout

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.