# Git submodule "Authentication failed" in CI

> Fix Git submodule authentication failures in CI, where the parent repo clones fine but a private submodule cannot authenticate during recursive checkout.

Source: https://latchkey.dev/learn/git/git-submodule-authentication-failed-in-ci  
Updated: 2026-06-26

The parent repository checked out, but a private submodule failed to authenticate. Submodules use their own recorded URLs and do not automatically inherit the parent clone credentials.

## Diagnose it: depth, refs, or credentials?

```Terminal
git rev-parse --is-shallow-repository
git rev-parse --abbrev-ref HEAD    # prints HEAD when detached
git log --oneline -3
git remote -v
```

> `actions/checkout` fetches depth 1 on a detached HEAD. Anything diffing against a base, reading a branch name, or running `git describe` needs `fetch-depth: 0`.

## FAQ

### What causes Git submodule "Authentication failed" in CI?

There are 3 common causes: submodule url lacks credentials, token without access to the submodule repo, and ssh submodule on an https-authenticated runner. The .gitmodules URL is plain HTTPS, so the recursive clone has no token even though the parent was authenticated.

### How do I fix Git submodule "Authentication failed" in CI?

There are 2 fixes depending on which cause you have: rewrite submodule auth globally and grant the token access to submodules. Work through them in order, since the first is the most common.

### What does Git submodule "Authentication failed" in CI actually mean?

A recursive checkout fails with fatal: clone of the submodule URL into the submodule path failed, after an authentication or "could not read Username" error against the submodule URL.

### How do I stop Git submodule "Authentication failed" in CI happening again?

Grant the CI credential access to every submodule repo, and use a github.com insteadOf rewrite so recursive clones inherit auth.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt