actions/checkout "could not read Username: terminal prompts disabled" in CI

By Daniel Zoghalchali·Latchkey

git needs credentials for a private HTTPS remote and found none, so it tried to prompt for a username. CI has no terminal, so git aborts with "terminal prompts disabled". The remote is private and no token was supplied to that fetch.

What this error means

A checkout or submodule fetch fails with "fatal: could not read Username for 'https://github.com': terminal prompts disabled". Public repos clone fine; the failure is always on a private repo or private submodule.

git

fatal: could not read Username for 'https://github.com': terminal prompts disabled
fatal: clone of 'https://github.com/acme/private-lib.git' into submodule path failed

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

The default GITHUB_TOKEN cannot read another private repo

actions/checkout authenticates the main repo with the automatic GITHUB_TOKEN, but that token is scoped to the current repository. A private submodule or second repo it does not cover gets an anonymous request, and git prompts.

A raw git clone step ran without embedding a token

A hand-written git clone https://github.com/org/repo step (outside actions/checkout) sends no credentials, so git falls back to prompting and fails.

How to fix it

Pass a token that can read every repo you fetch

Create a PAT or GitHub App token with read access to the private submodule/repo.
Store it as a secret and hand it to actions/checkout via the token input.
For submodules, the same token is reused when submodules is set.

.github/workflows/ci.yml

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

Rewrite HTTPS to an authenticated URL for raw clones

If you must clone by hand, inject the token into the URL via an insteadOf rewrite instead of an inline credential.

Terminal

git config --global url."https://x-access-token:${{ secrets.REPO_READ_PAT }}@github.com/".insteadOf "https://github.com/"
git clone https://github.com/acme/private-lib.git

How to prevent it

Use a token with read scope for every private repo a job touches, not just the current one.
Prefer actions/checkout with token and submodules over hand-written clone steps.
Never rely on the default GITHUB_TOKEN to reach a different private repository.

Frequently asked questions

What causes actions/checkout "could not read Username: terminal prompts disabled" in CI?

There are 2 common causes: the default github_token cannot read another private repo and a raw git clone step ran without embedding a token. actions/checkout authenticates the main repo with the automatic GITHUB_TOKEN, but that token is scoped to the current repository.

How do I fix actions/checkout "could not read Username: terminal prompts disabled" in CI?

There are 2 fixes depending on which cause you have: pass a token that can read every repo you fetch and rewrite https to an authenticated url for raw clones. Work through them in order, since the first is the most common.

What does actions/checkout "could not read Username: terminal prompts disabled" in CI actually mean?

A checkout or submodule fetch fails with "fatal: could not read Username for 'https://github.com': terminal prompts disabled".

How do I stop actions/checkout "could not read Username: terminal prompts disabled" in CI happening again?

Use a token with read scope for every private repo a job touches, not just the current one. The prevention section lists 3 changes that keep it from recurring.