GitHub Actions "The process '/usr/bin/git' failed with exit code 128"

A git command run by checkout returned exit code 128, a generic git fatal error, almost always because the runner could not authenticate to, resolve, or read the requested repository or ref.

What this error means

The checkout step fails with "The process '/usr/bin/git' failed with exit code 128", often preceded by a fatal: could not read from remote, authentication, or unknown-revision message.

fatal: could not read Username for 'https://github.com': terminal prompts disabled
The process '/usr/bin/git' failed with exit code 128

Common causes

Missing or insufficient token for private content

Checking out a private submodule or another private repo without a token that has access makes git fail to authenticate.

Bad ref or shallow-fetch depth

Requesting a ref or tag the fetch did not retrieve (fetch-depth too shallow) makes git fail with an unknown-revision fatal.

How to fix it

Provide access and the right fetch settings

1. Pass a token with access to private submodules/repos to actions/checkout.
2. Set submodules: recursive only with credentials that can read them.
3. Increase fetch-depth (or 0 for full history) when later steps need older refs.
4. Verify the target ref actually exists.

- uses: actions/checkout@v4
  with:
    submodules: recursive
    fetch-depth: 0
    token: ${{ secrets.GH_PAT }}

How to prevent it

• Grant explicit tokens for private submodule access.
• Set fetch-depth to match what downstream steps need.
• Validate that referenced tags/branches exist before checkout.

Related guides