Jenkins shared libraries examples
Jenkins is a widely used automation server in software development that helps teams automate their builds, tests, and deployments. Shared Libraries is one of its key features that allows users to create custom, reusable functions for automation pipelines. This article will explore the world of Jenkins Shared Libraries, exploring their benefits and guiding you through building custom reusable functions.
Table of contents
- Understanding Jenkins shared libraries
- How to set up your shared library repository
- How to import a shared library in Jenkins
- Best practices for Jenkins shared libraries
- Common errors and troubleshooting Jenkins shared libraries
- Conclusion
Understanding Jenkins shared libraries
What are Jenkins shared libraries?
When implementing Continuous Integration and Continuous Deployment (CI/CD) as code, it is essential to have modularity and reusability of the code. This is where the Jenkins Shared Library comes in. The Shared Library is a collection of independent Groovy scripts that can be pulled into your Jenkinsfile at runtime. The best part is that this library can be stored in a Git repository like everything else.
The Jenkins Shared Library allows you to have a common pipeline code in the version control system, which can be used by any number of pipelines simply by referring to it in the pipeline code. This reduces the effort for developers by keeping the same logic in multiple files.
Benefits of Jenkins shared libraries
Code Reusability
Shared Libraries eliminate duplicating code, fostering a more efficient and maintainable development process. When common tasks or functionalities are encapsulated into reusable functions within the library, developers can easily leverage them across multiple pipelines.
This saves time and ensures that changes or improvements to a particular function are reflected uniformly across all instances where it is utilized.
Consistency
By centralizing common functions, Shared Libraries ensure that all pipelines adhere to the same standards and best practices. This consistency is crucial for maintaining a uniform and reliable development and deployment process.
Teams can establish coding conventions, error-handling strategies, and deployment procedures within the Shared Library, guaranteeing that these practices are consistently applied throughout the organization.
Collaboration
Teams can collaborate effectively by sharing standardized functions and workflows through Shared Libraries. This collaboration extends beyond just sharing code; it creates a common language and set of tools all team members can leverage.
As a result, team members can easily understand and contribute to each other’s work, fostering a more cohesive development environment. This collaboration is precious in large projects with diverse teams, where maintaining a shared understanding of processes is crucial.
Easy Maintenance and Updates
Shared Libraries facilitate easy updates and maintenance. When a change or improvement is made to a function within the library, all pipelines using that function can instantly benefit from the update.
This centralized approach significantly reduces the effort required to implement changes, ensuring that the latest improvements are quickly integrated into all relevant pipelines. This saves time and minimizes the risk of inconsistencies or errors introduced by manual updates across multiple scripts.
Enhanced Testing
Shared Libraries provide opportunities for better testing practices. Since functions within the library can be isolated and unit-tested independently, developers can ensure the reliability and correctness of their code in a controlled environment.
This modular approach to testing improves the robustness of the Shared Library functions and facilitates more efficient troubleshooting when issues arise.
Key components of a Jenkins shared library
Repository Structure
Shared Libraries are typically organized within a version-controlled repository, such as Git. The repository structure often includes a dedicated directory named vars, where custom functions are defined.
Apart from the typical vars directory, additional directories may be used for grouping related functionality or organizing resources. For instance, a src
directory may contain utility scripts or other code snippets, while a resources
directory might store configuration files or documentation relevant to the shared library.
Groovy Scripts
The core of a Jenkins Shared Library is composed of Groovy scripts. These scripts contain the custom functions and logic developers want to reuse across pipelines. Groovy, a versatile scripting language, is well-suited for Jenkins Shared Libraries due to its concise syntax and seamless integration with Jenkins.
By taking advantage of Groovy’s features, these scripts are often written in a concise syntax that is easy to read and maintain. Developers can add comments and documentation to the scripts to improve their clarity. Groovy’s integration with Jenkins Pipeline DSL allows a seamless workflow using the shared library in pipeline scripts.
Global Variables
Shared Libraries often define global variables as entry points for accessing the library’s functions. These global variables are used in Jenkins pipeline scripts to import and utilize the custom functionality provided by the Shared Library.
Additionally, global variables may encapsulate configurations or settings that can be easily customized when using the shared library in different pipeline contexts.
How to set up your shared library repository
To create a shared library in Jenkins, you need to follow the steps mentioned below:
Organize your repository
Start by creating a Groovy script and saving it to a platform like Git, GitHub, GitLab, or Bitbucket to add it to the library.
#!/usr/bin/env groovy def greet(String message = 'automateNow!') { echo "Welcome to ${message}!" }
For example, this script defines a greet
function with a default parameter message
and uses echo
to print a greeting message.
Create a new repository on GitHub with a directory named vars. Save a script called sayHello.groovy
to the vars directory.
Set up shared library in Jenkins
Open the Jenkins dashboard in your respective web browser.
In your Jenkins dashboard, navigate to Manage Jenkins -> System.
Navigate to the Global Pipeline Libraries section and click the Add button.
A new dialog will be opened to help you set up library details, such as name and SCM method. Provide the Library Name (e.g., My_Shared_Library
) and specify the source code management option, including the Repository HTTPS URL.
Put the below-remaining details to complete your library configuration:
Default version: Add a default version for your new Shared Library, which may include a branch name, tag, or commit hash, depending on the SCM.
Load implicitly: Enabling this option grants automatic access to the library for scripts, eliminating the need for manual requests.
Allow default version to be overridden: Scripts can choose a specific library version by selecting this option.
Include @Library changes in job recent changes: If you enable this option, any changes made to the library will impact all library builds.
Cache fetched versions on master for quick retrieval: By enabling this option, Jenkins will store copies of the library it has fetched on the master node for future use.
Retrieval method: Choose Modern SCM or Legacy SCM from the dropdown menu. Opting for Modern SCM allows you to select an SCM plugin and configure relevant options.
Library Path (optional): This allows you to specify a relative path from the root of the SCM to the library directory.
Note
Under the Source Code Management dropdown, there are two options: Git and GitHub. You must select the tool you chose at the beginning for creating the repository.
After configuring the new library, click Save to apply changes to Jenkins.
Apply shared library in Jenkins Pipeline
Access the Jenkins dashboard and click on New Item. Then, enter the name of the job and select Pipeline as the project type. Finally, click the OK button.
Add a basic Groovy script that loads the shared library. Here, the println
statement is used for printing with a newline character at the end.
@Library('name_of_your_library') _ stage('Demo') { println 'Hello world' sayHello 'Ashutosh' }
Note:
Adding an underscore symbol (_) at the end of @Library
is necessary to avoid errors.
Then, click the Save button to apply the changes to the pipeline.
Click Build Now, and Jenkins will execute your pipeline. Then, click on the build number under Build History, and the Console Output link of the running build will appear.
To keep track of the progress of your pipeline, keep an eye on the console output. You’ll be able to see each stage being executed as it happens. Sample Console Output:
[Pipeline] @Library('name_of_your_library') _
[Pipeline] stage
[Pipeline] { (Demo)
[Pipeline] echo
Hello world
[Pipeline] sayHello
Greeting: Ashutosh
[Pipeline] }
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (New Stage)
[Pipeline] echo
This is a new stage
[Pipeline] customFunction
Custom Parameter: Custom Parameter
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // @Library('name_of_your_library')
[Pipeline] End of Pipeline
Finished: SUCCESS
Code language: PHP (php)
How to import a shared library in Jenkins
If a shared library fails to load automatically, Jenkins provides multiple ways to reference it using Groovy scripts.
Manually refer to the script by adding an annotation to the top of the Jenkins code:
@Library('[library_name]') _
Code language: JavaScript (javascript)
To load a specific library version, append the at symbol (@) followed by the version name:
@Library('[library_name] @ [library version]') _
Code language: JavaScript (javascript)
To load multiple libraries simultaneously, separate their names with a comma and a space.
@Library(['[library name 1]', '[library name 2]'])_
Code language: JavaScript (javascript)
It is possible to load a third-party library dynamically, which is not included in the Jenkins Global Pipeline Libraries settings.
For instance, if you want to load a library from Git, you must provide the library name, Jenkins class tag, the library’s Git URL, and valid credentials to access it. Consider using the library step within a pipeline block.
pipeline {
agent any
libraries {
lib('myLibrary@1.0') {
// Configuration for GitSCMSource
remote {
url 'https://github.com/example/my-library.git'
credentials 'my-git-credentials-id'
}
}
}
stages {
stage('Build') {
steps {
// Your build steps here
}
}
}
}
Code language: PHP (php)
Replace myLibrary@1.0
, https://github.com/example/my-library.git
, and my-git-credentials-id
with your actual library name, Git URL, and Git credentials ID, respectively.
Best practices for Jenkins shared libraries
Modular and atomic functions
When developing functions within a Jenkins Shared Library, it’s crucial to break down complex tasks into smaller, focused functions. This facilitates easy understanding and reuse and promotes encapsulation to protect the integrity of each function and minimize dependencies.
Users are encouraged to compose these smaller atomic functions to construct intricate workflows, providing a flexible and adaptable approach to pipeline development.
Clear and descriptive naming
Naming functions, variables, and classes enhances readability and user understanding. Opt for clear and descriptive names, adhering to consistent naming conventions throughout the Shared Library. Additionally, providing usage examples in documentation significantly assists users in quickly incorporating these well-named functions into their pipelines.
Documentation excellence
Comprehensive documentation is a cornerstone of a user-friendly Shared Library. Embedding in-code comments to explain complex logic, maintaining a detailed README file with an overview and installation instructions, and creating user guides or tutorials that showcase real-world scenarios contribute to a thorough understanding of the library’s functionalities.
Versioning strategy
Adopting a clear versioning strategy, such as semantic versioning (SemVer), is essential. Communicate changes effectively for each release through detailed release notes. Providing users with clear upgrade paths and guidelines ensures a smooth transition between different versions of the Shared Library.
Code review practices
Code reviews are integral to maintaining high-quality Shared Libraries. Define clear code review guidelines emphasizing best practices, coding standards, and conventions. A collaborative approach involving multiple team members ensures diverse perspectives and a consistent code quality. Integrating automated code analysis tools into the CI pipeline further enforces these practices.
Unit testing
Aim for high test coverage to ensure the functionality and correctness of Shared Library functions. Use tools that provide coverage metrics to assess the thoroughness of unit tests. Integrating unit tests into the CI pipeline facilitates automatic validation of code changes, promoting a reliable Shared Library.
Common errors and troubleshooting Jenkins shared libraries
Unable to load Jenkins shared libraries
Error message
ERROR: Could not find any definition of libraries [shared-library@master]
org.jenkinsci.plugins.workflow.cps.CpsCompilationErrorsException: startup failed:
Script1.groovy: Loading libraries failed
Code language: CSS (css)
Cause
This error typically occurs when Jenkins cannot locate the specified Shared Library on the specified branch (master). This issue may arise due to misconfigurations in the Jenkins global libraries settings, incorrect usage of the @Library
annotation in the Jenkinsfile, or connectivity problems with the Shared Library repository.
Troubleshooting
To resolve this issue, confirm that the Shared Library is correctly configured in the Jenkins global libraries settings and that the library name and version match the reference in your pipeline script. Ensure that the Shared Library repository is accessible and that the specified branch exists.
Additionally, check the @Library
annotation in your Jenkinsfile for syntax and placement accuracy. If the error persists, check for connectivity issues, permissions, or changes in the Shared Library repository that may have affected its availability.
Class path set up error
Error message
groovy.lang.MissingPropertyException: No such property: myorg for class: groovy.lang.Binding
at groovy.lang.Binding.getVariable(Binding.java:63)
at org.jenkinsci.plugins.scriptsecurity.sandbox.groovy.SandboxInterceptor.onGetProperty(SandboxInterceptor.java:264)
at org.kohsuke.groovy.sandbox.impl.Checker$6.call(Checker.java:288)
at org.kohsuke.groovy.sandbox.impl.Checker.checkedGetProperty(Checker.java:292)
at org.kohsuke.groovy.sandbox.impl.Checker.checke
Code language: HTTP (http)
Cause
This error is caused by the attempt to access the property myorg
in a Groovy script without it being defined or accessible in the current context. This can happen when the variable or property is not correctly declared, imported, or initialized in the script.
Troubleshooting
To resolve this issue, check the script for any typos in the variable name and ensure that it is correctly declared or imported. Verify the scope and context where the property is being used.
Additionally, if the script is executed within Jenkins and subject to the Script Security Plugin, consider adjusting the security settings to allow access to the specified property. Addressing these aspects should rectify the missing property exception.
Final thoughts on Jenkins Shared Libraries
Jenkins Shared Libraries offer a powerful way to improve the functionality and maintainability of your pipelines in Jenkins. By encapsulating typical tasks into reusable functions, you can simplify your CI/CD workflows, promote code consistency, and adapt to changing project requirements effectively. Embrace the potential of Jenkins Shared Libraries to advance your automation to the next level and make your pipeline code more reliable and maintainable.
Related articles
- How to create a pipeline in Jenkins
- Declarative vs scripted pipelines in Jenkins
- Jenkins architecture
- Jenkins-Git-SVN integration
- Mastering Jenkins credentials
- Jenkins in test automation
- Jenkins vs top competitors
Follow our blog
Be the first to know when we publish new content.
How to use Shared Libraries in Jenkins
- Top 10 API Testing Tools - April 6, 2024
- The ABCs of UAT Testing: Understanding User Acceptance Testing - March 21, 2024
- Agile Testing: Key Principles and Practices - March 15, 2024