GitHub Actions checkout "fatal: could not read Username" (submodules)

By Daniel Zoghalchali·Latchkey

actions/checkout authenticates the main repo with the workflow token, but private submodules are separate repositories. Without a token that can read them, the submodule clone falls back to an interactive HTTPS prompt that fails in CI.

What this error means

A checkout step with submodules: true or recursive fails cloning a submodule, asking for a Username it cannot read in a non-interactive shell.

fatal: could not read Username for 'https://github.com': No such device or address
fatal: clone of 'https://github.com/acme/private-lib' into submodule path '...' failed

Common causes

Default GITHUB_TOKEN cannot read the submodule repo

The automatic token is scoped to the workflow repository, not other private repositories referenced as submodules.

Submodule URL pinned to HTTPS without credentials

A .gitmodules HTTPS URL has no credential helper, so git prompts for a username.

How to fix it

Provide a token with submodule access

1. Create a PAT or GitHub App token that can read the submodule repos.
2. Pass it to checkout via the token input so it is used for submodules too.
3. Keep submodules: recursive if you have nested submodules.

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

How to prevent it

• Store a least-privilege token for cross-repo submodule reads.
• Prefer a GitHub App installation token over a long-lived PAT.
• Keep .gitmodules URLs consistent with the auth method you supply.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions