In this tutorial, you will learn how to create a basic shared library and integrate it with Jenkins and a sample pipeline.
Note: If you want to learn the shared library basic concepts and use cases, please take a look at this article.
We will look into the following four things to get your hands dirty with the shared library.
- Create a Shared Library Structure
- Create Custom Shared Library Code
- Configure Shared Library In Jenkins Configuration
- Create Declarative Pipeline as Code With Shared Library.
Let looks at each one in detail.
Create a Shared Library Structure
Note: In this guide, we will be concentrating only on the vars folder for creating your first shared library. src and resources will be covered in the advanced shared library guide.
Jenkins shared library has the following structure. You can get the basic structure and code used in this article from Github -> Jenkins Shared Library Structure
jenkins-shared-library
|____vars
|____src
|____resources
All the files under vars are global functions and variables. The file name is the function name. We will be using the filename in our declarative pipeline.
Create Custom Shared Library Code
In this section, we will create the shared library code for Git Checkout functionality.
Generate Pipeline Syntax Using Snippet Generator:
You can create the code snippets that can be used in share library function using the Pipeline Syntax Generator available in Jenkins. This will make our life easier for creating custom library DSL. All the supported pipeline functionality can be generated from the snippet generator.
You can access the syntax generator from your Jenkins on /pipeline-syntax/ path. For example,
http://devopscube-jenkins.com:8080/pipeline-syntax/
Here is the screenshot which shows creating a git checkout pipeline snippet using the pipeline syntax generator.
Number 5 in the screenshot shows the generated snippet. Here is the properly formatted checkout snippet.
checkout([
$class: 'GitSCM',
branches: [[name: '*/master']],
doGenerateSubmoduleConfigurations: false,
extensions: [],
submoduleCfg: [],
userRemoteConfigs: [[url: 'https://github.com/spring-projects/spring-petclinic.git']]
])
Create a Shared Library For Git Checkout
Lets convert the checkout snippet we generated in the above step to a shared library.
Create a file named gitCheckout.groovy
under vars folder.
Here is our Git Checkout shared library code. We have removed all the empty checkout parameters which got generated by default.
def call(Map stageParams) {
checkout([
$class: 'GitSCM',
branches: [[name: stageParams.branch ]],
userRemoteConfigs: [[ url: stageParams.url ]]
])
}
Here is the code explanation,
def call(Map stageParams)
– A simple call function which accepts a Map as an argument. From the pipeline stage, we will pass multiple arguments which get passed as a map to the shared library.stageParams.branch
– its the branch parameter which comes from the pipeline stage and we usestageParams
to access that variable in the shared library.
Commit the changes and push it to your repository.
Add Github Shared Library Repo to Jenkins
Now that we have a basic git checkout library ready lets add it to Jenkins configurations.
Step 1: Go to Manage Jenkins –> Configure System
Step 2: Find the Global Pipeline Libraries section and add your repo details and configurations as shown below.
Use Checkout Library in Declarative Pipeline
We always call the library using the filename under vars. In this case, gitCheckout is the filename created under vars. Here is how we call gitCheckout
library from the pipeline or Jenkinsfile
stage('Git Checkout') {
gitCheckout(
branch: "master",
url: "https://github.com/spring-projects/spring-petclinic.git"
)
}
As you can see we are passing branch
and url
parameter to the Checkout function. Here is the full declarative pipeline code.
@Library('[email protected]') _
pipeline {
agent any
stages {
stage('Git Checkout') {
steps {
gitCheckout(
branch: "master",
url: "https://github.com/spring-projects/spring-petclinic.git"
)
}
}
}
}
Like gitCheckout, you can create all your pipeline steps a shared library and you don’t have to repeat your common functionalities in all your pipelines.
3 comments
@ramesh pashamr Did you find a solution to this problem? I’m getting the same error.
Hi, thank you for this very helpful .
I am trying to create a shared library of withDockerContainer
My .groovy file code is :
I am not sure if it is syntactically correct to write image: stageParams
Also, my pipeline code is :
Hi,
Tried same way as you said but while loading shared library I am getting following error..