GitHub Actions Checkout Submodule Fails - Private Submodule Auth
A checkout with submodules fails on a private or cross-repo submodule because the default GITHUB_TOKEN cannot read it, or the submodule uses an SSH URL the runner has no key for.
What this error means
actions/checkout with submodules: true or recursive fails fetching a submodule with a 403 / authentication error, while the main repo checks out fine.
fatal: could not read Username for 'https://github.com': terminal prompts disabled
Error: fetching submodule libfoo failed
# or
git@github.com: Permission denied (publickey).Diagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
Common causes
Default token cannot read the submodule repo
The built-in GITHUB_TOKEN is scoped to the current repository. A private submodule in another repo is not readable with it.
Submodule uses an SSH URL
A .gitmodules entry with a git@github.com: URL needs an SSH key on the runner; checkout cannot authenticate it with an HTTPS token.
How to fix it
Pass a token that can read the submodule
Use a PAT or GitHub App token with access to the submodule repositories so checkout can fetch them over HTTPS.
- uses: actions/checkout@v4
with:
submodules: recursive
token: ${{ secrets.SUBMODULE_PAT }}Use an SSH key or rewrite the URL
- Add an SSH deploy key with webfactory/ssh-agent and set submodules: recursive.
- Or convert SSH submodule URLs to HTTPS so the token-based auth applies.
- Confirm the .gitmodules paths and URLs are correct and reachable.
Catch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow to prevent it
- Provide a scoped PAT or App token for private submodules.
- Standardize submodule URLs on HTTPS for token auth in CI.
- Limit submodule fetch depth where full history is not needed.