How to Configure SSH Agent in Jenkins for Secure Git Access

To configure ssh-agent in Jenkins, install the SSH Agent plugin, add your SSH private key in Jenkins credentials, and then enable the SSH Agent build step in your job to use that key during builds. This allows Jenkins to authenticate with Git or remote servers securely without exposing passwords.

Syntax

The basic steps to configure ssh-agent in Jenkins involve these parts:

• SSH Agent Plugin: A Jenkins plugin that manages SSH keys during builds.
• Credentials: Store your SSH private key securely in Jenkins.
• Build Step: Use the SSH Agent build wrapper to activate the key during the job.

groovy

sshagent(credentials: ['your-ssh-credential-id']) {
  // your build steps here
}

Example

This example shows how to configure a Jenkins Pipeline to use the SSH Agent plugin with a stored SSH key credential to clone a private Git repository.

groovy

pipeline {
  agent any
  stages {
    stage('Clone Repo') {
      steps {
        sshagent(['my-ssh-key-id']) {
          sh 'git clone [e-mail]:youruser/yourrepo.git'
        }
      }
    }
  }
}

Output

Cloning into 'yourrepo'...
remote: Enumerating objects: 10, done.
remote: Counting objects: 100% (10/10), done.
remote: Compressing objects: 100% (8/8), done.
Receiving objects: 100% (10/10), done.

Common Pitfalls

Common mistakes when configuring SSH Agent in Jenkins include:

• Not installing the SSH Agent plugin before using it.
• Using incorrect or missing SSH credentials ID in the job configuration.
• Not adding the private key correctly in Jenkins credentials (must be private key, not public).
• Forgetting to wrap build steps inside the sshagent block in Pipeline jobs.
• SSH key permissions issues on the Jenkins server.

groovy

/* Wrong: Missing sshagent block */
pipeline {
  agent any
  stages {
    stage('Clone Repo') {
      steps {
        sh 'git clone [e-mail]:youruser/yourrepo.git'
      }
    }
  }
}

/* Right: Using sshagent block */
pipeline {
  agent any
  stages {
    stage('Clone Repo') {
      steps {
        sshagent(['my-ssh-key-id']) {
          sh 'git clone [e-mail]:youruser/yourrepo.git'
        }
      }
    }
  }
}

Quick Reference

Summary tips for configuring SSH Agent in Jenkins:

• Install the SSH Agent plugin from Jenkins Plugin Manager.
• Add your SSH private key in Manage Jenkins > Credentials.
• Use the sshagent(['credential-id']) block in Pipeline scripts.
• Wrap all Git or SSH commands inside the sshagent block.
• Test SSH access manually on Jenkins server to verify key permissions.

Key Takeaways

Install the SSH Agent plugin to manage SSH keys in Jenkins builds.

Store your SSH private key securely in Jenkins credentials.

Wrap build steps needing SSH access inside the sshagent block in Pipeline.

Use the correct credentials ID matching your stored SSH key.

Verify SSH key permissions on the Jenkins server to avoid access errors.