Back to blog

Jenkins Windows Services: YAML Configuration Support - GSoC Project Results

Buddhika Chathuranga
August 27, 2020

Hello, world! GSoC 2020 Phase 3 has ended now and it was a great period for the Jenkins Windows Services - YAML Configuration Support project. In this blog post, I will announce the updates during the GSoC 2020 - Phase 2 and Phase 3. If you are not already aware of this project, I would recommend reading this blog post which was published after GSoC 2020 - Phase 1.

Project Scope

  • Windows Service Wrapper - YAML configuration support

  • YAML schema validation

  • New CLI

  • XML Schema validation

YAML Configuration Support

Under WinSW - YAML configurations support, these tasks will be done.

YAML to Object mapping

At the moment YAML object mapping is finished and merged. You can find all the implementations in this Pull Request.

Extend WinSW to support both XML and YAML

This task is already done and merged. Find the implementation in this Pull Request.

YAML Configuration support for Extensions

At the moment there are 2 internal plugins in WinSW. RunAwayProcessKiller and SharedDirectoryMapper. We allow users to provide configurations for those plugins in the same XML and YAML configuration file which is used to configure WinSW. This task is merged as well. Pull Request

YAML schema validation

Users can validate YAML configuration file against JSON schema file. Users can use YAML utility tool from Visual Studio market place to validate YAML config file against JSON schema.

Key updates in Phase 2 and Phase 3

Sample YAML Configuration File

id: jenkins
name: Jenkins
description: This service runs Jenkins automation server.
env:
    - name: JENKINS_HOME
      value: '%LocalAppData%\Jenkins.jenkins'
    - name: LM_LICENSE_FILE
      value: host1;host2
executable: java
arguments: >-
    -Xrs -Xmx256m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle
    -jar "E:\Winsw Test\yml6\jenkins.war" --httpPort=8081
log:
    mode: rotate
onFailure:
    - action: restart
      delay: 10 sec
    - action: reboot
      delay: 1 hour
extensions:
    - id: killOnStartup
      enabled: yes
      classname: WinSW.Plugins.RunawayProcessKiller.RunawayProcessKillerExtension
      settings:
            pidfile: '%BASE%\pid.txt'
            stopTimeOut: 5000
            StoprootFirst: false
    - id: mapNetworDirs
      enabled: yes
      classname: WinSW.Plugins.SharedDirectoryMapper.SharedDirectoryMapper
      settings:
            mapping:
                - enabled: false
                  label: N
                  uncpath: \\UNC
                - enabled: false
                  label: M
                  uncpath: \\UNC2

New CLI

Let me explain in brief, why we need a new CLI. In WinSW, we will keep both XML and YAML configuration support. But according to the current implementation, the user can’t specify the configurations file explicitly. Also, we want to let the user skip the schema validation as well. So We decided to move into new CLI which is more structured with commands and options. Please read my previous blog post to learn more about commands and options in the new CLI.

Key updates in Phase 2 and Phase 3

  • Remove the /redirect command

  • testwait command was removed and add the wait option to the test command.

  • stopwait command was removed and add the wait option to the stop command.

How to try

User can configure the Windows Service Wrapper by both XML and YAML configuration files using the following steps.

  1. Create the configuration file (XML or YAML).

  2. Save it with the same name as the Windows Service Wrapper executable name.

  3. Place the configuration file inside the directory(or in a parent directory), where the Windows Service Wrapper executable is located.

If there are both XML and YAML configuration files, Windows Service Wrapper will be configured by the XML configuration file.

GSoC 2020 Phase 2 Demo

GSoC 2020 Phase 3 Demo

Future Works

  • XML Schema validation

    • XML configuration file will be validated with the XSD file. I have started working on this feature and you can find the implementation in this Pull Request.

  • YAML Configuration validate on startup

How to contribute

You can find the GitHub repository in this link. Issues and Pull requests are always welcome. Also, you can communicate with us in the WinSW Gitter channel, which is a great way to get in touch and there are project sync up meetings every Tuesday at 13:30 UTC on the Gitter channel.

About the author

Buddhika Chathuranga

This author has no biography defined. See social media links referenced below.