Validating JCasC configuration files using Visual Studio Code
Configuration-as-code plugin
Problem Statement: Convert the existing schema validation workflow from the current scripting language in the Jenkins Configuration as Code Plugin to a Java based rewrite thereby enhancing its readablity and testability supported by a testing framework for the same. Enhance developer experience by developing a VSCode Plugin to facilitate autocompletion and validation which would help the developer write correct yaml files before application to a Jenkins Instance.
The Configuration as Code plugin has been designed as an opinionated way to configure Jenkins based on human-readable declarative configuration files. Writing such a file should be feasible without being a Jenkins expert, just translating into code a configuration process one is used to executing in the web UI. The plugin uses a schema to verify the files being applied to the Jenkins instance.
With the new JSON Schema being enabled developers can now test their yaml file against it. The schema checks the descriptors i.e. configuration that can be applied to a plugin or Jenkins core, the correct type is used and help text is provided in some cases. VSCode allows us to test out the schema right out of the box with some modifications. This project was built as part of the Community Bridge initiative which is a platform created by the Linux Foundation to empower developers — and the individuals and companies who support them — to advance sustainability, security, and diversity in open source technology. You can take a look at the Jenkins Community Bridge Project Page
Steps to Enable the Schema Validation
a) The first step includes installing the JCasC Plugin for Visual Studio Code and opening up the extension via the extension list. Shortcut for opening the extension list in VSCode editor using Ctrl + Shift + X.
b) In order to enable validation we need to include it in the workspace settings.
Navigate to File and then Preference and then Settings. Inside settings search for json and inside settings.json include the following configuration.
{
"yaml.schemas": {
"schema.json": "y[a]?ml"
}
}You can specify a glob pattern as the value for schema.json which is the file name for the schema. This would apply the schema to all yaml files. eg: .[y[a]?ml]
c) The following tasks can be done using VSCode:
a) Auto completion (Ctrl + Space): Auto completes on all commands.
b) Document Outlining (Ctrl + Shift + O): Provides the document outlining of all completed nodes in the file.
d) Create a new file under the work directory called jenkins.yml. For example consider the following contents for the file:
jenkins:
systemMessage: “Hello World”
numExecutors: 2-
The above yaml file is valid according to the schema and vscode should provide you with validation and autocompletion for the same.
Screenshots
We are holding an online meetup on the 26th February regarding this plugin and how you could use it to validate your YAML configuration files. For any suggestions or discussions regarding the schema feel free to join our gitter channel. Issues can be created on Github.