Jenkins Job Builder is quite modular. It is easy to add new attributes to existing components, a new module to support a Jenkins plugin, or include locally defined methods to deal with an idiosyncratic build system.
The Builder class manages Jenkins jobs. It’s responsible for creating/deleting/updating jobs and can be called from your application. You can pass it a filename or an open file-like object that represents your YAML configuration. See the jenkins_jobs/builder.py file for more details.
Most of the work of building XML from the YAML configuration file is handled by individual functions that implement a single characteristic. For example, see the jenkins_jobs/modules/builders.py file for the Python module that implements the standard Jenkins builders. The shell function at the top of the file implements the standard Execute a shell build step. All of the YAML to XML functions in Jenkins Job Builder have the same signature:
Parameters: |
|
---|
The function is expected to examine the YAML data structure and create new XML nodes and attach them to the xml_parent element. This general pattern is applied throughout the included modules.
Nearly all of Jenkins Job Builder is implemented in modules. The main program has no concept of builders, publishers, properties, or any other aspects of job definition. Each of those building blocks is defined in a module, and due to the use of setuptools entry points, most modules are easily extensible with new components.
To add a new module, define a class that inherits from jenkins_jobs.modules.base.Base, and add it to the jenkins_jobs.modules entry point in your setup.py.
A base class for a Jenkins Job Builder Module.
The module is initialized before any YAML is parsed.
Parameters: | registry (ModuleRegistry) – the global module registry. |
---|
The component list type will be used to look up possible implementations of the component type via entry points (entry points provide a list of components, so it should be plural). Set both component_type and component_list_type to None if module doesn’t have components.
The component type for components of this module. This will be used to look for macros (they are defined singularly, and should not be plural). Set both component_type and component_list_type to None if module doesn’t have components.
Update the XML element tree based on YAML data. Override this method to add elements to the XML output. Create new Element objects and add them to the xml_parent. The YAML data structure must not be modified.
Parameters: |
|
---|
This method is called before any XML is generated. By overriding this method, the module may manipulate the YAML data structure on the parser however it likes before any XML is generated. If it has changed the data structure at all, it must return True, otherwise, it must return False.
Parameters: | parser (YAMLParser) – the global YAML Parser |
---|---|
Return type: | boolean |
The sequence number for the module. Modules are invoked in the order of their sequence number in order to produce consistently ordered XML output.
Most of the standard modules supply a number of components, and it’s easy to provide your own components for use by those modules. For instance, the Builders module provides several builders, such as the shell builder as well as the trigger_builds builder. If you wanted to add a new builder, all you need to do is write a function that conforms to the Component Interface, and then add that function to the appropriate entry point (via a setup.py file).
All modules and their associated components are registered in the module registry. It can be accessed either from modules via the registry field, or via the parser parameter of components.
This is a method that you can call from your implementation of Base.gen_xml or component. It allows modules to define a type of component, and benefit from extensibility via Python entry points and Jenkins Job Builder Macros.
Parameters: |
|
---|
See jenkins_jobs.modules.base.Base for how to register components of a module.
See the Publishers module for a simple example of how to use this method.