# Private submodule authentication (token or ssh-key) in CI

> Fix private submodule authentication in CI - the parent repo checks out but a private submodule fails to fetch because the checkout token or SSH key does not cover it.

Source: https://latchkey.dev/learn/git/gcs-submodule-private-auth-token-in-ci  
Updated: 2026-06-30

A private submodule needs its own credential. actions/checkout can fetch submodules only if the token (for HTTPS) or ssh-key (for SSH) it holds can read that submodule repository. The default GITHUB_TOKEN cannot read a different private repo.

## 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 Private submodule authentication (token or ssh-key) in CI?

There are 2 common causes: the default token is scoped to the parent repo only and the submodule url style does not match the credential. GITHUB_TOKEN authenticates the current repository.

### How do I fix Private submodule authentication (token or ssh-key) in CI?

There are 2 fixes depending on which cause you have: give checkout a credential that covers the submodule (https token) and or use a deploy key and url rewrite for ssh submodules. Work through them in order, since the first is the most common.

### What does Private submodule authentication (token or ssh-key) in CI actually mean?

Submodule update fails with an auth error ("could not read Username" for HTTPS, or "Permission denied (publickey)" for SSH) even though the parent repo cloned successfully.

### How do I stop Private submodule authentication (token or ssh-key) in CI happening again?

Provision a token or deploy key that can read every private submodule. The prevention section lists 3 changes that keep it from recurring.

---

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