Git submodule "Authentication failed" in CI

By Daniel Zoghalchali·Latchkey

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.

What this error means

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.

git

fatal: could not read Username for 'https://github.com': No such device or address
fatal: clone of 'https://github.com/org/private-sub.git' into submodule path 'vendor/sub' failed
Failed to clone 'vendor/sub'. Retry scheduled

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

Common causes

Submodule URL lacks credentials

The .gitmodules URL is plain HTTPS, so the recursive clone has no token even though the parent was authenticated.

Token without access to the submodule repo

A fine-grained PAT or App installation scoped only to the parent cannot read the private submodule.

SSH submodule on an HTTPS-authenticated runner

A git@ submodule URL needs an SSH key even when the parent used an HTTPS token.

How to fix it

Rewrite submodule auth globally

Use an insteadOf rewrite so every github.com URL carries the token.
Then run the recursive update.

Terminal

git config --global url."https://x-access-token:${GH_PAT}@github.com/".insteadOf "https://github.com/"
git submodule update --init --recursive

Grant the token access to submodules

Extend the PAT or App installation to include every submodule repo.
On actions/checkout, pass a token with submodule access and set submodules: recursive.

.github/workflows/ci.yml

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

How to prevent it

Grant the CI credential access to every submodule repo, and use a github.com insteadOf rewrite so recursive clones inherit auth. A retry will not fix a credential that cannot see the submodule.

Frequently asked questions

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.