Git authentication failure

What this failure means

The CI runner could not authenticate with the remote Git repository. This prevents cloning, fetching, or pushing code.

Symptoms

Faultline looks for one or more of these log fragments:

terminal prompts disabled
could not read username
authentication failed for
repository not found
remote: invalid username or password
fatal: credential helper
exit code 128

Diagnosis

The CI runner could not authenticate with the remote Git repository. This prevents cloning, fetching, or pushing code.

Fix steps

1. For HTTPS, prefer the CI provider’s checkout or credential helper instead of embedding a token in a global URL rewrite. In GitHub Actions, use the actions/checkout step with token: ${{ secrets.GITHUB_TOKEN }} so the credential is injected for the job only.

2. For SSH: add the deploy key or SSH key as a CI secret, then load it:

   eval "$(ssh-agent -s)"
   echo "$SSH_KEY" | ssh-add -
   

3. Verify the token has the required scope:

   • GitHub PAT: needs repo (private repos) or read:packages.
   • Deploy key: needs read (or read+write for push) on the specific repo.

4. Confirm the remote URL scheme matches the credentials you have:

   git remote -v
   

5. Test the credential before the full workflow step:

   git ls-remote origin HEAD
   

Validation

• git ls-remote origin HEAD exits 0 and prints the current HEAD SHA.
• Re-run the failing clone, fetch, or push step and confirm no authentication error appears.

Why it matters

CI environments disable interactive terminal prompts, so Git cannot prompt for a username and password. Without a pre-configured credential or SSH key, the operation fails immediately.

Prevention

• Use a dedicated CI service account with the minimum repository permissions needed.
• Prefer short-lived tokens (GitHub Actions GITHUB_TOKEN) over persistent PATs.
• Document the required secret names in your repository README.
• Add a lightweight clone or fetch smoke step to validate repository credentials before long build stages begin.

Try it locally

git ls-remote <repo-url>
git ls-remote <repo-url>

How Faultline detects it

Use faultline explain git-auth to see the full playbook.

faultline analyze build.log
faultline explain git-auth

Generated from playbooks/bundled/log/auth/git-auth.yaml. Do not edit directly.