Global YAML Properties

The Global YAML Properties Plugin is a universal extension for Jenkins that enhances Jenkins configuration by adding a Global YAML Configuration page. This page allows users to define global properties in YAML format, which is then parsed into a HashMap and can be accessed throughout specific build step. The same mechanism is used for Local YAML Configuration, but it is defined in the project's configuration page.

Plugin simplifies the management of global properties and configurations by centralizing them within Jenkins. You can define key-value pairs, nested structures, and arrays using YAML, making it easier to express complex relationships.

Once the properties are saved, they are automatically parsed into a HashMap, enabling easy access throughout your Jenkins pipelines or jobs. This promotes dynamic and customizable workflows.

With the Global YAML Properties Plugin, you can efficiently manage environment-specific variables, deployment settings, and other configurable parameters. Say goodbye to scattered configuration files and embrace streamlined configuration management within Jenkins.

1. Backward compatibility for shared libraries: The Global YAML Properties Plugin aims to ensure backward compatibility for private shared libraries that contain environment-specific information such as IP addresses, ports, and other configuration details. By centralizing and managing these properties within the plugin, it allows for easier maintenance and updates, ensuring smooth integration with existing libraries.

2. Unify handling of actual configuration: The plugin provides a unified and centralized location to handle actual configurations used across various places within Jenkins. As configurations may change or become deprecated over time, the Global YAML Properties Plugin offers a streamlined approach to manage and update these configurations effectively. By consolidating them in one place, it promotes consistency and simplifies the configuration management process.

Real life example: You have self-hosted shared library that obtains toolchain from FTP to workspace and builds your product by running some commands. Build commands and FTP address can be changed over time. Now imagine situation when you need to build old version of your product. You have to build product using old version of shared library, where FTP address is deprecated. Global YAML Properties Plugin allows you to define FTP address in one place and update it easily. In shred library you can just obtain value from global configuration and it will be always correct across all versions of shared library.

1. Think twice about configurations and format you want to put into global properties. If the keys and format changes frequently, this eliminates the benefit of backwards compatibility.

2. DO NOT put there sensitive data like passwords or tokens. If you need to put there some sensitive data, you can use Credentials Plugin and Credentials Binding Plugin to access them in your pipeline. In this case global properties can be nice feature for handling credential IDs.

At first, define your YAML configuration in the global configuration page of Jenkins.

Manage Jenkins -> Global YAML Configuration

There is two types of configuration sources:

• Manual: manually defined YAML configuration
• GitHub: YAML configuration from GitHub repository

To use GitHub configuration, you need to specify the following parameters:

• Repository Name: Name of the repository
• Branch/Commit ref: Any GitHub reference (branch, tag, or commit SHA) that uniquely identifies the commit
• Path to YAML file: Path to YAML file in repository
• GiHub App Credentials: GitHub App credentials to access repository

To validate GitHub configuration source, click Obtain Configuration button. If validation is successful, you will see configuration that will be obtained from source and parsed.

When using GitHub configuration source, you may want to specify Refresh Interval parameter to not overload GitHub API. It can be done at top of the page. Accepted values are between 1 and 50000 (minutes).

Please note, that GitHub configuration also fetched every time when you click Save button on the page. When commit hash is specified as reference, configuration will not be fetched periodically to save API Request limit usage.

Now, you can access the configuration in your pipeline or freestyle job.

Also, you can configure who will have access to the Global YAML Configuration page.

Manage Jenkins -> Configure Global Security

Using plugin https://plugins.jenkins.io/matrix-auth/ you can configure permissions for specific users or groups to access the Global YAML Configuration page. In case if user has no access to manage Jenkins, there is still ability to view YAML conifgurations (if view permission on YAML Configurations is granted). To view configuration just visit the following URL: <jenkins_url>/manage/globalyamlconfiguration/ By default, only Administrators have read/edit access to the Global YAML Configuration page.

Local YAML Configuration is a configuration that is defined in the project's configuration page. Only people who have access to project's configuration can view or edit Local YAML Configuration.

Local YAML Configuration can also be defined for multibranch pipeline jobs. In this case, Local YAML Configuration will be defined in the configuration of the multibranch pipeline job, not in the configuration of the branch job.

Step getGlobalYAMLProperties without arguments returns HashMap object which is parsed from default YAML configuration. Default YAML configuration is the first configuration in the list of Global Configuration. Step getLocalYAMLProperties without arguments returns HashMap object which is parsed from project's YAML configuration.

Here is pipeline example which explains access to the configuration:

def myProperties = getGlobalYAMLProperties()
String message = "Message for:\n${myProperties['devopsTeam'].join('\n')}\n"
message += "Guys, you don't need to update FTP server into each pipeline separately,\n"
message += "I've put FTP address to Global Properties and updated it easily in one place.\n"
message += "Let's go drink beer."
echo message
String ftpCommand = "curl -O ftp://${myProperties.ftpServerAddress}/path/to/file"
println "Command to download file from internal ftp:"
println ftpCommand

Pipeline output:

Also you can use step getGlobalYAMLProperties with argument name to get specific config by name from Global Configuration.

def myProperties = getGlobalYAMLProperties("Test")
println myProperties.myValue

Pipeline output:

Here are complete steps definitions:

Report issues and enhancements in the Jenkins issue tracker. Do not forget to specify component as global-yaml-properties-plugin.

1. Fork repository
2. Create PR accordingly to template into source repository
3. Wait for review

Licensed under MIT, see LICENSE