Jenkins Windows Services: YAML Configuration Support

Goal: Enhance Jenkins controller and agent service management on Windows by offering new configuration file formats and improving settings validation

Status: Completed



On Windows machines, Jenkins controller and agents can be installed as Windows Services to get better robustness and manageability within the system. This is a functionality bundled into the Jenkins core directly. When installed as a service, Jenkins uses the Windows Service Wrapper executable (.NET, written in C#) which is being configured by XML config files. Currently, there are only a few configuration checks there (no XML Schema, limited validation, etc.), and it’s often that the service wrapper is misconfigured by Jenkins users.

In this project, we propose to update Windows Service Wrapper to support YAML files as configuration inputs and to introduce better configuration validation during the service installation and startup. The usage of YAML should simplify configuration management in Jenkins, especially when automated tools are used.


  • Service Descriptor: YAML Support

  • Validations for Configs

  • Schema validation for YAML (JSON)

  • Unit Test for Validations

  • Project Guideline Documentation

  • Sample YAML config files

    • Sample-alloption.yaml

    • Sample-minimal.yaml

Phase 1

  • YAML service Descriptor

  • Start implementing configurations verification on startup

  • Project Guideline documentation

  • Blog Post 1

Phase 2

  • Finish implementation of configurations verification on startup

  • Start implementing YAML schema validation

  • Minimal Viable Product will be released

  • Blog Post 2

Phase 3

  • Finish implementation of YAML schema validation

  • Sample YAML config files

  • Blog Post 3

During each phase, the respective unit test will be added to the existing Unit Test library.

Current Status

MVP has been released. This release contains the following features.

Further Improvements

  • Configuration validation on Startup

    • Environment variable expansion and validation is left to do.

  • Integrate YAML schema validation

    • Currently, users can validate the YAML file with JSON schema externally. We have to integrate this feature into the Windows service wrapper.

Key Pull Requests

Remaining tasks

  • New CLI

    • New CLI is almost done. Have to merge with V3.

  • XML schema validation

    • XSD schema has been created and integrated. Have to update documentation and validations in the XSD schema.

  • Integrate the new Windows Service Wrapper into the Jenkins core

Contact us

Office hours are scheduled every Tuesday at 13:30 UTC in the project’s Gitter chat. Meeting notes are available here to read.

See the GSoC Project application draft for more details.