WindowsマシンをJNLP方式でJenkinsエージェントに追加する

はじめに

Jenkinsエージェントに関するドキュメント(Using Jenkins agents)にWindowsマシンをJNLP方式で追加する方法が記載されていなかったため、手順をまとめました。

環境

• Jenkins: version 2.516.1

前提

• JenkinsのWebアプリケーションにhttp://jenkins-hostname:8080/でアクセスできるものとする。

手順

Jenkins管理画面でのエージェント追加

1. Jenkinsの管理画面http://jenkins-hostname:8080/manage/computerにアクセスし、「New Nodes」ボタンを押下する。
2. 「ノード名」のテキストボックスに任意のエージェント名を入力し(e.g., windows-agent)、「Permanent Agent」ラジオボタンを選択して「Create」ボタンを押下する。「ノード設定」画面が表示される。
3. 「リモートFSルート」テキストボックスにエージェントマシン上のJenkins用ディレクトリパスを入力する。(e.g., C:\Users\agent-machine-username\jenkins)
4. 「起動方法」プルダウンメニューから「Launch agent by connecting it to the controller」を選択する。
5. 「Save」ボタンを押下する。作成したエージェントの詳細画面が表示される。

WindowsマシンにJavaをインストール

エージェントマシンとなるWindowsマシンで以下の手順を実施する。

1. 以下のコマンドでJavaのインストール状況を確認する。Version情報が表示されない場合はJavaがインストールされていないため、手順2以降を実施する。

   java -version
   

2. 以下のコマンドを実行する。

   winget install -e --id Microsoft.OpenJDK.21 --source winget
   

3. 再度Javaのインストール状況を確認する。Version情報が表示されればインストール完了。

   java -version
   

   openjdk version "21.0.8" 2025-07-15 LTS
   OpenJDK Runtime Environment Microsoft-11933218 (build 21.0.8+9-LTS)
   OpenJDK 64-Bit Server VM Microsoft-11933218 (build 21.0.8+9-LTS, mixed mode, sharing)
   

Windowsマシンからの接続確認

1. 以下のコマンドでagent.jarをダウンロードする。

   cd C:\Users\agent-machine-username\jenkins
   curl.exe -sO http://jenkins-hostname:8080/jnlpJars/agent.jar
   

2. 以下のコマンドでエージェントマシンからJenkinsコントローラへ接続する。

   cd C:\Users\agent-machine-username\jenkins
   java -jar agent.jar -url http://jenkins-hostname:8080/ -secret YourSecretLetters -name "trial-node" -webSocket -workDir "C:\Users\agent-machine-username\jenkins"
   

3. http://jenkins-hostname:8080/computer/your-windows-agent-name/にアクセスし、エージェントの状態が「Agent is connected.」になっていることを確認する。

Windows Serviceとしての登録

ここまでの手順では、WindowsマシンのPowerShell上でエージェントを起動しているため、PowerShellを閉じるとエージェントも停止してしまいます。エージェントをWindows Serviceとして登録するには以下の手順を実施します。

1. https://github.com/winsw/winsw/releases/latestからWindows Service Wrapperの実行形式をWindowsマシンのアーキテクチャに合わせてをダウンロードする。以下の手順ではWinSW-x64.exeをダウンロードしたものとして記述する。

2. ダウンロードしたWinSW-x64.exeをC:\Users\agent-machine-username\jenkins\jenkins-agent.exeにリネームして配置する。

3. 以下のXMLを記述したファイルjenkins-agent.xmlをC:\Users\agent-machine-username\jenkinsに配置する。注意点として、XMLファイル名の拡張子以外をリネームした実行ファイルと同じにし、.xmlと.exeの2つのファイルを同じフォルダに配置する必要がある。

   <service>
     <!-- ID of the service. It should be unique across the Windows system-->
     <id>jenkins-agent</id>
     <!-- Display name of the service -->
     <name>Jenkins Agent</name>
     <!-- Service description -->
     <description>Jenkins agent service for this Windows machine</description>
   
     <!-- Path to the executable, which should be started -->
     <executable>"C:\Program Files\Microsoft\jdk-21.0.8.9-hotspot\bin\java.exe"</executable>
     <arguments>-jar "C:\Users\agent-machine-username\jenkins\agent.jar" -url http://jenkins-hostname:8080/ -secret YourSecretLetters -name "y01-0693941" -webSocket -workDir "C:\Users\agent-machine-username\jenkins"</arguments>
     <log mode="roll"></log>
   </service>
   

4. 以下のコマンドを実行して、Window Serviceとしてインストールする。

   cd C:\Users\agent-machine-username\jenkins
   .\jenkins-agent.exe install
   

5. 以下のコマンドを実行して、Windows Serviceをスタートする。

   cd C:\Users\agent-machine-username\jenkins
   .\jenkins-agent.exe start
   

6. http://jenkins-hostname:8080/computer/your-windows-agent-name/にアクセスし、エージェントの状態が「Agent is connected.」になっていることを確認する。

おわりに

WindowsマシンをJNLP方式でJenkinsエージェントに追加する手順についてまとめました。SSH方式での接続を確立するのが難しい場合などに参考になれば幸いです。