Jenkins SSH Agent Docker Image

By default, host keys are generated inside the container and change every time the container is recreated, which may cause Jenkins to lose trust in the host. To prevent this, you can persist host keys in a mounted volume (e.g., /mnt/agent).

Implementation Pattern:

1. Create a directory in the mounted volume for host keys (e.g., /mnt/agent/host_keys/).
2. In your entrypoint script, copy existing keys from the volume to /etc/ssh/.
3. Run ssh-keygen -A to ensure all keys are generated.
4. Copy the keys back from /etc/ssh/ to the volume to persist them for the next run.

#!/bin/bash
# /mnt/agent is the mounted volume
mkdir -p /mnt/agent/host_keys/

cp -u /mnt/agent/host_keys/ssh_host*_key* /etc/ssh/

ssh-keygen -A

cp -u /etc/ssh/ssh_host*_key* /mnt/agent/host_keys/

setup-ssd "$@"

To run a standalone container for testing or manual connection, use docker run. You must provide a public SSH key via the JENKINS_AGENT_SSH_PUBKEY environment variable.

Key Configuration:

• User: The default user is jenkins.
• Port: The container listens on port 22. You can map this to a host port (e.g., 2200) to connect via ssh jenkins@localhost -p 2200.
• Remote Root Directory (Linux): /home/jenkins/agent
• Remote Root Directory (Windows): C:/Users/jenkins/Work

If you use a custom directory, ensure you mount it as a volume.

docker run -d --rm --name=agent --publish 2200:22 -e "JENKINS_AGENT_SSH_PUBKEY=<public_key>" jenkins/ssh-agent

When using the SSH Build Agents plugin, configure the agent in the Jenkins UI with the following settings:

1. Credentials: Use the private key that matches the public key provided during container startup.
2. Remote root directory:
   • For Linux images: /home/jenkins/agent
   • For Windows images: C:/Users/jenkins/Work

If you intend to use a different directory, you must mount it as a data volume in your Docker configuration.

# Example of mounting a custom directory for a Linux agent
docker run -v docker-volume-for-jenkins-ssh-agent:/home/jenkins/agent:rw jenkins/ssh-agent "<public key>"

To use this image with the Docker Plugin, follow these steps in the Docker Agent Template configuration:

1. Environment Variables: In the Environment field (advanced section), add the public SSH key using the JENKINS_AGENT_SSH_PUBKEY key. Do not use quotes around the key.
   • Format: JENKINS_AGENT_SSH_PUBKEY=<YOUR PUBLIC SSH KEY HERE>
2. Remote File System Root: Set this value to /home/jenkins/agent in the configuration UI.

If using a custom directory, ensure it is added as a Docker volume.

JENKINS_AGENT_SSH_PUBKEY=ssh-rsa AAAAB3Nza... user@host

You can extend the image using a Dockerfile. When copying files, ensure you use the correct ownership for the jenkins user and reference the ${JENKINS_AGENT_HOME} variable if necessary.

FROM jenkins/ssh-agent:debian-jdk25 as ssh-agent
# [...]
COPY --chown=jenkins mykey "${JENKINS_AGENT_HOME}"/.ssh/mykey
# [...]