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