A Jenkins agent image which allows using SSH to establish the connection. It can be used together with the SSH Build Agents plugin or other similar plugins.
See Jenkins Distributed builds for more info.
To run a Docker container
docker run -d --rm --name=agent --publish 2200:22 -e "JENKINS_AGENT_SSH_PUBKEY=<public_key>" jenkins/ssh-agent
-d
: To start a container in detached mode, use the -d
option. Containers started in detached mode exit when the root process used to run the container exits, unless you also specify the --rm option.--rm
: If you use -d with --rm, the container is removed when it exits or when the daemon exits, whichever happens first.--name
: Assigns a name to the container. If you do not specify a name, Docker generates a random name.--publish 2200:22
: Publishes the host port 2200 to the agent container port 22 (SSH) to allow connection from the host with ssh jenkins@localhost -p 2200
Please note none of these options are mandatory, they are just examples.
You will then be able to connect this agent using the SSH Build Agents plugin as "jenkins" with the matching private key.
When using the Linux image, you have to set the value of the Remote root directory
to /home/jenkins/agent
in the agent configuration UI.
When using the Windows image, you have to set the value of the Remote root directory
to C:/Users/jenkins/Work
in the agent configuration UI.
If you intend to use another directory than /home/jenkins/agent
under Linux or C:/Users/jenkins/Work
under Windows, don't forget to add it as a data volume.
docker run -v docker-volume-for-jenkins-ssh-agent:/home/jenkins/agent:rw jenkins/ssh-agent "<public key>"
To use this image with Docker Plugin, you need to pass the public SSH key using environment variable JENKINS_AGENT_SSH_PUBKEY
and not as a startup argument.
In Environment field of the Docker Template (advanced section), just add:
JENKINS_AGENT_SSH_PUBKEY=<YOUR PUBLIC SSH KEY HERE>
Don't put quotes around the public key.
Please note that you have to set the value of the Remote File System Root
to /home/jenkins/agent
in the Docker Agent Template configuration UI.
If you intend to use another directory than /home/jenkins/agent
, don't forget to add it as a data volume.
You should be all set.
Should you need to extend the image, you could use something along those lines:
FROM jenkins/ssh-agent:debian-jdk17 as ssh-agent
# [...]
COPY --chown=jenkins mykey "${JENKINS_AGENT_HOME}"/.ssh/mykey
# [...]
The image has several supported configurations, which can be accessed via the following tags:
${IMAGE_VERSION}
can be found on the releases page.
latest
, latest-jdk11
, jdk11
, latest-bookworm-jdk11
, bookworm-jdk11
, latest-debian-jdk11
, debian-jdk11
, ${IMAGE_VERSION}
, ${IMAGE_VERSION}-jdk11
, (Dockerfile)latest-jdk17
, jdk17
, latest-bookworm-jdk17
, bookworm-jdk17
, latest-debian-jdk17
, debian-jdk17
, ${IMAGE_VERSION}-jdk17
, (Dockerfile)nanoserver-1809
, nanoserver-ltsc2019
, nanoserver-1809-jdk11
, nanoserver-ltsc2019-jdk11
, ${IMAGE_VERSION}-nanoserver-1809
, ${IMAGE_VERSION}-nanoserver-ltsc2019
, ${IMAGE_VERSION}-nanoserver-1809-jdk11
, ${IMAGE_VERSION}-nanoserver-ltsc2019-jdk11
(Dockerfile)windowsservercore-1809
, windowsservercore-ltsc2019
, windowsservercore-1809-jdk11
, windowsservercore-ltsc2019-jdk11
, ${IMAGE_VERSION}-windowsservercore-1809
, ${IMAGE_VERSION}-windowsservercore-ltsc2019
, ${IMAGE_VERSION}-windowsservercore-1809-jdk11
, ${IMAGE_VERSION}-windowsservercore-ltsc2019-jdk11
(Dockerfile)Should you want to build this image on your machine (before submitting a pull request for example), please have a look at the pre-requisites:
19.03
). Docker Buildx is included in recent versions of Docker Desktop for Windows, macOS, and Linux. Docker Linux packages also include Docker Buildx when installed using the DEB or RPM packages.If you want to see the target images that will be built, you can issue the following command:
make list
alpine_jdk11
alpine_jdk17
debian_jdk11
debian_jdk17
If you want to build a specific image, you can issue the following command:
make build-<OS>_<JDK_VERSION>
That would give for JDK 17 on Alpine Linux:
make build-alpine_jdk17
Then, you can build the images supported by your current architecture by running:
make build
If you want to test these images, you can run:
make test
If you want to test a specific image, you can run:
make test-<OS>_<JDK_VERSION>
That would give for JDK 17 on Alpine Linux:
make test-alpine_jdk17
You can build all images (even those unsupported by your current architecture) by running:
make every-build
make
targetsshow
gives us a detailed view of the images that will be built, with the tags, platforms, and Dockerfiles.
make show
{
"group": {
"default": {
"targets": [
"alpine_jdk17",
"alpine_jdk11",
"debian_jdk11",
"debian_jdk17",
]
}
},
"target": {
"alpine_jdk11": {
"context": ".",
"dockerfile": "alpine/Dockerfile",
"tags": [
"docker.io/jenkins/ssh-agent:alpine-jdk11",
"docker.io/jenkins/ssh-agent:latest-alpine-jdk11"
],
"platforms": [
"linux/amd64"
],
"output": [
"type=docker"
]
},
[...]
bats
is a dependency target. It will update the bats
submodule and run the tests.
make bats
make: 'bats' is up to date.
publish
allows the publication of all images targeted by 'linux' to a registry.
docker-init
is dedicated to Jenkins infrastructure for initializing docker and isn't required in other contexts.
Run .\build.ps1
to launch the build of the images corresponding to the "windows" target of docker-bake.hcl.
Internally, the first time you'll run this script and if there is no build-windows.yaml file in your repository, it will use a combination of docker buildx bake
and yq
to generate a build-windows.yaml docker compose file containing all Windows image definitions from docker-bake.hcl. Then it will run docker compose
on this file to build these images.
You can modify this docker compose file as you want, then rerun .\build.ps1
.
It won't regenerate the docker compose file from docker-bake.hcl unless you add the -OverwriteDockerComposeFile
build.ps1 parameter: .\build.ps1 -OverwriteDockerComposeFile
.
Note: you can generate this docker compose file from docker-bake.hcl yourself with the following command (require docker buildx
and yq
):
# - Use docker buildx bake to output image definitions from the "windows" bake target
# - Convert with yq to the format expected by docker compose
# - Store the result in the docker compose file
$ docker buildx bake --progress=plain --file=docker-bake.hcl windows --print `
| yq --prettyPrint '.target[] | del(.output) | {(. | key): {\"image\": .tags[0], \"build\": .}}' | yq '{\"services\": .}' `
| Out-File -FilePath build-windows.yaml
Note that you don't need build.ps1 to build (or to publish) your images from this docker compose file, you can use docker compose --file=build-windows.yaml build
.
Run .\build.ps1 test
if you also want to run the tests harness suit.
Run .\build.ps1 test -TestsDebug 'debug'
to also get commands & stderr of tests, displayed on top of them.
You can set it to 'verbose'
to also get stdout of every test command.
Note that instead of passing -TestsDebug
parameter to build.ps1, you can set the $env:TESTS_DEBUG environment variable to the desired value.
Also note that contrary to the Linux part, you have to build the images before testing them.
Add the -DryRun
parameter to print out any build, publish or tests commands instead of executing them: .\build.ps1 test -DryRun
You can build (and test) only one image type by setting -ImageType
to a combination of Windows flavors ("nanoserver" & "windowsservercore") and Windows versions ("1809", "ltsc2019", "ltsc2022").
Ex: .\build.ps1 -ImageType 'nanoserver-ltsc2019'
Warning: trying to build windowsservercore-1809
will fail as there is no corresponding image from Microsoft.
See GitHub Releases. Note that the changelogs and release tags were introduced in Dec 2019, and there are no entries for previous releases. Please consult with the commit history if needed.