Why am I unable to authenticate via sshagent inside docker?

2 minute read


sshagent step consistently or intermittently does not work within the docker.image().inside {} block.



The SSH Agent Plugin bundles a few ssh-agent implementation. When Pipeline enters the sshagent step, it will print out the selection process into a Console Output. If the implementation was selected successfully and the misconfiguration is ruled out, there are two possible causes.

1. Version of SSH Agent Plugin does not support Docker Pipeline

Version 1.10 adds the support for the Docker Pipeline. This the minimum version you should use for the sshagent step to work inside the Docker container.

2. Selected ssh-agent implementation does not consistently work with Docker

If the version of the plugin is greater than 1.10 but less than 1.14, you are most likely affected by the issue JENKINS-36997, see the root cause analysis below. You can fix the problem by upgrading the SSH Agent Plugin to 1.14 or newer and installing ssh-agent command inside Docker container. If ssh-agent is not available inside the container, the plugin will fallback to the earlier implementation, which is still affected. If you cannot satisfy either of conditions, you can work the issue around by changing the location of the workspace to avoid deep nesting which leads to a long absolute file path of the socket.

Root cause

Jenkins Agent running on the node that serves as a Docker host itself acts as an SSH Agent. By default, it creates the Unix socket in the Workspace temp directory to enable communication with the processes that require access to the keys. However, if the length of the absolute path of the socket file inside Workspace temp is greater than 108 (max path length restriction on the Unix domain socket, ref), it is instead created in the default system temp directory.

Processes inside the docker container communicate with the same SSH Agent described above. This is made possible by the automatic mounting of the Workspace and Workspace temp directories. Unfortunately, this means that if the Jenkins Agent was forced to create the socket in the system temp instead of the Workspace one, processes inside the container are not able to access it.