Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

git says it could not read Username for https://github.com in a build or CI job

Errorfatal: could not read Username for 'https://github.com': No such device or address

Short answer

Git asked for HTTPS credentials and there was no terminal to ask on, so it gave up. A private repository needs a token supplied to the job. In docker build pass it as a build secret, in GitHub Actions use the checkout token input, and for a private build context use BuildKit's GIT_AUTH_TOKEN.

  • Applies to Git 2.4x, Docker Buildx 0.2x, GitHub Actions actions/checkout
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find the line that runs git clone or git fetch against github.com over https, and see whether the job passes any token to it. Then decide which of the three causes below is yours.

    grep -rn "github.com" Dockerfile .github/workflows/ .gitmodules 2>/dev/null
  2. 2Match what you see, then jump to its fix

    1. 1The failing line is a RUN step during docker build, and the repository is private.RUN git clone of a private repository inside a DockerfileFix
    2. 2The error comes from actions/checkout, a git submodule update, or a script step, and the repository is not the one the workflow runs in.A GitHub Actions job fetches another private repository or submoduleFix
    3. 3docker build https://github.com/my-org/my-app.git fails before any Dockerfile step runs.docker build uses a private GitHub URL as its contextFix

What does the error look like?

  • fatal: could not read Username for 'https://github.com': No such device or address

Cause 1 of 3

RUN git clone of a private repository inside a Dockerfile

1Check

A build step has no terminal, so git cannot prompt. Git's GIT_TERMINAL_PROMPT setting also stops terminal prompts when it is false. Nothing in the step gives git a user name or password.

grep -n "git clone" Dockerfile

2Fix

Pass a personal access token as a build secret, and give git a one-off credential helper that reads it. A secret mount exists for one instruction only and does not stay in the image, unlike ARG or ENV.

# Dockerfile
RUN --mount=type=secret,id=GITHUB_TOKEN \
    git -c 'credential.helper=!f() { echo username=my-github-user; echo "password=$(cat /run/secrets/GITHUB_TOKEN)"; }; f' \
    clone https://github.com/my-org/private-repo.git /src

# build command
docker build --secret id=GITHUB_TOKEN,env=GITHUB_TOKEN .

3Verify

The clone step passes and the token is not in the image history.

docker history --no-trunc my-image | grep -i token || echo clean

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

A GitHub Actions job fetches another private repository or submodule

1Check

The default GITHUB_TOKEN is scoped to the current repository. A different private repository, or private submodules, need your own token or an SSH key.

grep -n -B2 -A6 "actions/checkout" .github/workflows/*.yml

2Fix

Store a personal access token as a repository secret and pass it to checkout through the token input; add submodules when needed. A classic token needs the repo scope for command-line access.

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

3Verify

Re-run the workflow; checkout completes and the submodule folders are filled.

git submodule status

Confirmed by github.com

Did this fix it?

Cause 3 of 3

docker build uses a private GitHub URL as its context

1Check

BuildKit fetches a remote Git context itself, and it needs a token for a private repository.

docker build https://github.com/my-org/my-app.git

2Fix

Provide the token through BuildKit's pre-defined GIT_AUTH_TOKEN secret.

GIT_AUTH_TOKEN=$(gh auth token) docker build \
  --secret id=GIT_AUTH_TOKEN \
  https://github.com/my-org/my-app.git

3Verify

The build starts and reaches the first Dockerfile instruction.

docker build --progress=plain --secret id=GIT_AUTH_TOKEN https://github.com/my-org/my-app.git

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Use a fine-grained or classic token scoped to the repositories the job needs, and store it as a secret, never in the Dockerfile.
  • Never pass tokens with ARG or ENV in a Dockerfile; Docker says build arguments and environment variables are not suitable for secrets.
  • Prefer cloning in the CI job and copying the source into the build over cloning inside the image.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

docker pull or push to ghcr.io fails with 'denied'

Error response from daemon: denied

ghcr.io refuses a pull or push when Docker is not logged in, when the token lacks the package scope, or when the workflow's GITHUB_TOKEN has no packages permission or no access to that package.

4 causes, each with a fix

Servers

A GitHub Actions workflow builds the Docker image but cannot push it

The push step fails right after the login step

Four things stop a push from GitHub Actions: build-push-action does not push unless push is true, the Docker Hub login used a password instead of an access token, the workflow token lacks packages write for ghcr.io, or the run comes from a fork, where the token is read-only.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.