GitHub Actions checkout "submodule recursive auth failed"

actions/checkout with submodules: recursive uses GITHUB_TOKEN, which only has access to the current repository. Private submodules in other repositories cannot be cloned with that token, so the recursive fetch fails. This is an auth-scope issue.

What this error means

Checkout succeeds for the main repo but fails fetching a private submodule, asking for credentials it cannot supply.

fatal: could not read Username for 'https://github.com': terminal prompts disabled
Error: fetching submodule 'libs/private' failed

Common causes

GITHUB_TOKEN scoped to one repo

The default token cannot authenticate to private submodule repos hosted elsewhere.

No token provided to checkout for submodules

checkout was not given a token with access to the submodule repositories.

How to fix it

Provide a token with submodule access

1. Create a PAT or GitHub App token with read access to the submodule repos.
2. Pass it to actions/checkout via the token input with submodules: recursive.
3. Store it as a secret; never inline it.

- uses: actions/checkout@v4
  with:
    submodules: recursive
    token: ${{ secrets.SUBMODULE_TOKEN }}

How to prevent it

• Use a token with access to every private submodule repository.
• Keep the submodule token least-privilege and stored as a secret.

Related guides