How to Connect SSH in Jenkins and Use It in Pipelines

Jenkins is widely used for automating deployments and builds. Often, you need to connect to remote servers via SSH to run commands, deploy applications, or manage Docker containers. This guide explains how to set up SSH in Jenkins and use it in pipelines safely and efficiently.

---

1. Prerequisites

Before connecting Jenkins to a remote server via SSH:

1. A running Jenkins instance

   • Can be installed directly or via Docker.

2. Remote server access

   • IP/hostname, username, and private key for SSH access.

3. Required Jenkins plugins

   • SSH Agent Plugin (for pipelines)
   • Optional: SSH Steps Plugin (provides sshCommand, sshScript)

---

2. Install SSH Plugins

1. Go to Manage Jenkins → Manage Plugins → Available.
2. Search for SSH Agent Plugin and install it.
3. (Optional) Install SSH Steps Plugin if you prefer sshCommand or sshScript.
4. Restart Jenkins after installation.

⚠️ Make sure to install the SSH Agent Plugin specifically; other SSH-related plugins serve different purposes.

---

3. Prepare SSH Credentials

1. Go to Manage Jenkins → Manage Credentials → System → Global credentials (unrestricted).
2. Click Add Credentials.
3. Choose Kind → SSH Username with private key.
4. Fill in the details:

Field	Description
Username	SSH user on the remote server (e.g., root or ubuntu)
Private Key	Paste the private key (e.g., id_rsa)
Passphrase	Leave empty if key has no passphrase
ID	Identifier to use in the pipeline (e.g., ssh-server-key)
Description	Optional description

5. Click Save.

✅ This allows Jenkins to authenticate to the remote server without passwords.

---

4. Test SSH Access from Jenkins

If Jenkins is running in a container:

1. Make sure the container has SSH client installed:

docker exec -it jenkins bash
apt update
apt install -y openssh-client

2. Test manually:

ssh -i /var/jenkins_home/.ssh/id_rsa user@SERVER_IP "ls -la"

If this works, Jenkins will be able to run commands via SSH.

---

5. Use SSH in a Jenkins Pipeline

A. Using SSH Agent Plugin (Recommended)

pipeline {
    agent any
    stages {
        stage('Run Remote Command') {
            steps {
                sshagent(['ssh-server-key']) {
                    sh '''
                        ssh -o StrictHostKeyChecking=no root@SERVER_IP "
                            echo Connected!;
                            ls -la /home/root
                        "
                    '''
                }
            }
        }
    }
}

Explanation:

• sshagent(['ssh-server-key']) loads the private key stored in Jenkins credentials.
• The ssh command connects to the remote server.
• -o StrictHostKeyChecking=no avoids prompts for unknown hosts (use with care).

B. Using SSH Steps Plugin (Alternative)

pipeline {
    agent any
    stages {
        stage('Run Remote LS') {
            steps {
                sshCommand remote: [
                    host: 'SERVER_IP',
                    user: 'root',
                    identityFile: '/var/jenkins_home/.ssh/id_rsa',
                    port: 22
                ], command: "ls -la /home/root"
            }
        }
    }
}

• This avoids using sshagent and shell commands.
• identityFile points to the private key location.

---

6. Common Use Cases

Deploying Docker containers remotely:

sshagent(['ssh-server-key']) {
    sh '''
        ssh root@SERVER_IP "
            docker pull myuser/myapp:latest &&
            docker stop myapp || true &&
            docker rm myapp || true &&
            docker run -d --name myapp -p 80:80 myuser/myapp:latest
        "
    '''
}

Copying files with SCP:

sshagent(['ssh-server-key']) {
    sh 'scp -o StrictHostKeyChecking=no localfile.txt root@SERVER_IP:/var/www/html/'
}

Running scripts remotely:

sshagent(['ssh-server-key']) {
    sh 'ssh root@SERVER_IP "/home/root/deploy.sh"'
}

---

7. Best Practices

1. Use Jenkins credentials instead of hardcoding passwords or keys.
2. Avoid using StrictHostKeyChecking=no in production; instead, manage known hosts.
3. Keep private keys secure and never expose them in pipeline scripts.
4. Test connectivity manually first to debug network or firewall issues.
5. Use folder or project-based credentials if different teams need isolated access.

---

8. Summary

Using SSH in Jenkins pipelines allows secure remote automation. The SSH Agent Plugin is the recommended method for Declarative or Scripted Pipelines. By storing credentials securely and using sshagent, you can run commands, deploy applications, and manage Docker containers on remote servers directly from Jenkins.