Introduction

The checkout scm step in Jenkins Pipelines clones the source code repository using credentials configured in Jenkins. When these credentials are missing, expired, or lack access to the repository, the checkout fails and the entire pipeline aborts. This is a common failure point after credential rotation, repository permission changes, or Jenkins migration.

Symptoms

  • Pipeline fails at the first step with checkout scm error
  • Console output shows fatal: Authentication failed or could not read Username
  • Pipeline worked previously but started failing after credential rotation
  • Error message: ERROR: Error cloning remote repo 'origin': Could not clone git@github.com:org/repo.git
  • Error message: fatal: could not read Username for 'https://github.com': terminal prompts disabled

Common Causes

  • SSH key credential rotated and the new key not updated in Jenkins
  • GitHub/GitLab personal access token expired
  • Jenkins credential ID referenced in the pipeline does not exist
  • Repository was made private and the service account lost access
  • Git credential helper not configured on the agent node

Step-by-Step Fix

  1. 1.Check the credential configuration in Jenkins: Verify the credential exists and is correct.
  2. 2.`
  3. 3.# Jenkins UI: Manage Jenkins > Manage Credentials
  4. 4.# Find the credential used by the pipeline (check Pipeline SCM config)
  5. 5.# Test the credential by connecting to the Git server
  6. 6.`
  7. 7.Test Git access from the Jenkins agent: Verify credentials work on the agent.
  8. 8.```bash
  9. 9.# For SSH
  10. 10.ssh -T git@github.com
  11. 11.# Should show: Hi username! You've successfully authenticated

# For HTTPS with token GIT_ASKPASS=echo git clone https://<token>@github.com/org/repo.git /tmp/test-clone ```

  1. 1.Update the Jenkins credential with valid authentication: Replace the expired credential.
  2. 2.`
  3. 3.# Jenkins UI: Manage Jenkins > Manage Credentials > select domain > Update
  4. 4.# For SSH: paste the new private key
  5. 5.# For HTTPS: enter the new personal access token
  6. 6.`
  7. 7.Verify the pipeline SCM configuration references the correct credential ID: Check the pipeline config.
  8. 8.```groovy
  9. 9.// Declarative pipeline
  10. 10.pipeline {
  11. 11.agent any
  12. 12.options {
  13. 13.// Ensure the credential ID matches what's configured in Jenkins
  14. 14.// checkout scm automatically uses the configured credential
  15. 15.}
  16. 16.stages {
  17. 17.stage('Checkout') {
  18. 18.steps {
  19. 19.checkout scm
  20. 20.}
  21. 21.}
  22. 22.}
  23. 23.}
  24. 24.`
  25. 25.Re-run the pipeline: Verify checkout succeeds.
  26. 26.`
  27. 27.# Jenkins UI: Click the pipeline > Build Now
  28. 28.# Check console output for successful clone
  29. 29.`

Prevention

  • Use service accounts (not personal tokens) for Jenkins Git credentials
  • Set up credential expiration monitoring and rotate before expiry
  • Document all credential IDs used by each pipeline in a central registry
  • Test Git credentials after any token or key rotation
  • Use SSH keys over HTTPS for better security and no expiration issues
  • Implement pipeline health checks that verify SCM connectivity on startup