Getting Started With Shared Libraries in Jenkins

in today's video we're going to be getting started with shared libraries in jenkins [Music] are you new here if you are welcome and if you are new here you don't know who i am my name is darren pope and i'm a developer advocate for cloudbees when you're first starting with declarative pipelines and jenkins you're probably starting out really small and simple but over time that grows and you keep adding more and more stages sometimes though there's things you want to do so you go and grab an old copy of a pipeline put it in the new job make a couple of changes but then there's one section that's always exactly the same that's where a shared library can come in and help with the shared library we can create what we'll call a custom step and from there we can reuse that step in all of our pipelines why is that such a great thing being able to create your own custom step without having to create a plug-in makes your life much easier and simpler because it's a much easier problem to solve as you can see here this is the documentation for shared libraries the great thing about it it's all on one page at jenkins io the link for this documentation will be right below this video now let's take a look through it so you can understand what a shared library is and what it can do for you much like i just said we want to be able to reuse parts of pipelines between different projects we'll be going through an example of that in just a few moments the thing about a shared library is that it has a very specific directory structure i've got a separate git repository that we're going to be using for our shared library as we go through this demonstration but there's up to three top level folders in this repository there's going to be vars resources and source now in our example today we're only going to be working inside of vars using resources and source are more advanced topics that we'll visit in another video since we're just going to be taking a look at vars today let's take a look at the documentation as it's called out these are going to host the files that are exposed as a variable i previously used the phrase custom step so anything that is in vars is considered to be a global variable from a jenkins perspective so when we create files inside of vars they'll be named whatever the step is that we want to call and then dot groovy now these files are not groovy files but the extension needs to be a dot groovy extension also you can create a dot txt file that matches the groovy file name and that will be the help that shows up in the global variables in order to use these shared libraries we first have to set it up inside of our controller and we'll do this live in a few moments but to get to this you'll go to manage jenkins and then configure system and we'll scroll down to the global pipeline library section and we'll see what that looks like you can also create shared libraries at a folder level whether that's actually a folder or maybe it's a multi-branch pipeline you can also create the shared libraries at that level the big difference between the global and the folder level is that the folder based libraries are not considered trusted so they run just in the sandbox just like how your pipelines run we're not going to go through the rest of this documentation right now but i do want to make sure that you're aware of one thing before we get into it when we actually call and use our shared library we'll be using this annotation at library at the top of our pipeline but then i want you to notice one thing right here the space and the underscore now the space and underscore treat it like let's say you're a java developer this is sort of like saying import package dot star the space underscore says hey give me everything that's inside of the shared library because you could specify hey i only want handfuls of certain things but in our case we want to be able to load up the complete shared library we're now at our jenkins controller login screen so we're going to go ahead and log in and just for reference this is jenkins lts 2.263.2 this setup that we're getting ready to go through has not changed in a very very long time so what we're going to go into is we're going to go over here to manage jenkins configure system let's go ahead and scroll down to global pipeline libraries almost there and it says shareable libraries available this is exactly what we want great click on add and i'm probably going to have to scroll over here just a little bit there we go and let me zoom back out okay there we go okay we're going to give it a name now this this will be the name that we will reference in our pipeline files to be able to use this shared library i'm just going to call mine shared library the default version can be a branch name a tag or even a commit hash now the way that my repository is currently set up i have a branch in there and the branch is called master there are a couple of different settings here i recommend leaving these as default until you start to understand more what they do for you in short load implicitly means anytime a pipeline runs this shared library will be loaded whether you're using anything from it or not i personally prefer always saying hey i want to load up the libraries that i want so i typically do not check load implicitly the allow default version to be overridden gives you the ability to say hey by default it's going to be mastered but maybe i want to pull in from a different tag or a different commit hash or even a completely different branch if i allow the default version to be overridden then that's great but i might not want people doing that in real life production as i'm doing development right now this is helpful so i'm going to leave it checked and include at library changes and job recent changes i always just leave that checked now let's go and get hooked up to my git repository i'm going to select modern scm then i'm going to select get and i'm going to go out to github and the link to this repository will be down in the description i'm going to grab the clone url and i'm going to grab the https version of it since this is a public repository i don't have to worry about credentials i'll do that and that's it that's all that i need to do for a basic setup there are other things you can do through behaviors if you needed to again a shared library repository is meant to be used just for the shared library don't put anything else in there it's meant to do one specific thing don't put a shared library structure in with bunches of other files it's meant to do one thing only okay that's all i need to do to get it set up so i'm going i'm going to go ahead and click on save but before we continue i'm going to go back over to manage jenkins configure system we're going to go back down there again and if you look under master now you can see that master currently maps to revision cd0f if we go back over to my repository you can see that my latest commit is cd0f so this helps me validate that i'm able to use or that i'm able to map to this specific get branch along with its and i'm validating that the commit hash was the same so i know i'm looking at what i expect to see okay so we have wired in our shared library into our controller now let's go through a sequence of events and understand how we will be able to use that shared library in just a few moments now the shared library that i have here has lots of different examples some in better health than others the one that we'll be taking a look at is what we're going to be focusing on if you come back and look at this later some of these may or may not be working that's okay these are just some examples that you may or may not be able to use okay let's head back over to our controller i'm going to create a new job and i'm going to call it test pipeline whoops gotta select pipeline first there we go in a normal situation you would not be putting your pipeline directly into this pipeline script block but i'm doing that for this demonstration purpose all right i'm going to go and grab an example very simplistic pipeline so if we paste this in here you're going to see and i will go ahead and bump this back up there we go we've got pipeline i'm going to be using an agent that has a label of linux and i'm going to run a very simple step it's just going to be sh echo hello world very very simple click on save let's see what happens here i click on build now and looking at the output we can see that this is a very lightweight console log i basically want you to look at the shape of this console log and what i mean by shape is it's pretty short just a couple of lines and that's it as we move forward you're going to see this change over time so basically all we have here is echo hello world well let's go to the top it was started by admin it's running in performance optimized it's running on agent one and then it does the echo and that's done which is exactly what our pipeline was written to do very very very simple this is the place you want to start but now what i want to do is i want to modify this echo hello world and i actually want to call a custom step that i have in fact let's go ahead and go over take a look at it i've already prepared for this up front i have a hello world custom step already created it's in vars and it's hello world notice that it's camel cased if you go back and take a look at the documentation it recommends using camel case for the file names inside of vars if it needs to be camel cased and what we're going to be doing is we're going to be extracting out the sh echo hello world and we're putting it inside of this def call closure so call is what's used and is the default for what we're going to be calling from here so i'm going to change this to hello world when i call hello world with just the open and close parentheses that will call this call value and then what is inside of this will be executed okay so let's go ahead and do one more thing the one thing that we forgot to do here is we need to bring in that library so i'm going to do an at upper l library and in quotes i'm going to do shared library and if you remember back in the documentation i'm doing the space underscore so i don't forget to pull in everything from the shared library you want to keep your shared libraries usually fairly small small in file count which determines back to disk size because every time a pipeline runs that shared library is being cloned into the workspace so it's a very key part so if your shared library is large meaning large megs that could impact your runtime probably not by a lot but it could impact it so i've got at library shared library space underscore i have changed my sh to just hello world let's click save and we will click on build now let's see what happens here going back to that first run that we did remember i said to take a look at the shape of the console log now take a look at it we've got admin performance optimized and right here loading library shared library at master what does that mean we had our at library annotation in our pipeline we gave it a name of shared library but we didn't specify master where does that come from so if you were to go back and take a look at the configuration we saw a shared library it has a default of master it's pulled together and now we're able to clone in the master branch from that repository that's configured against shared library everything that we see here down to here is all associated to the clone of the shared library and you can see here that the rest of this pipeline just ran as expected so the only thing extra that we received was this clone for our shared library repository so when you're first starting out introducing a shared library in keep it really simple don't try to build out everything to begin with just get one simple step in there make sure it imports in make sure it does what you're expecting before you move on to create bigger things so let's go back to our configuration here and we can see that we were calling hello world which was this value right here hello world groovy now let's assume for a moment that i don't like how i'm echoing this field out i'm going to make a change to the value of hello world or the render of hello world just because i want it to be uppercase so i'm going to say upper h upper w i commit the change and now i've got upper h upper w i'm not making any changes to my pipeline this is the power of a shared library custom step because i can make that change and anybody that's using that custom step will receive that change when they run their job the next time so let's go ahead and do that so we do a build now we'll go back over here and take a look at the output of three we go down here to the output and we see echo upper h upper w exactly what i wanted i made zero changes to the pipeline i made the change to my custom step which is my file inside of the vars folder inside of the shared library repository so now i'm ready to move on to make that a little more complex just a little what does that mean so what i want to do now is i want to pass in two parameters i'm going to pass in my name and the day of the week so let's edit this file i'm going to say string name string day of week and i'm going to modify my output to use those variables today is day of week oops of week okay that looks good let's go ahead and click on commit changes and then let's modify our pipeline to pass in those parameters whoops i hit the wrong thing pipeline to pass in those parameters so what i have here is darren and today is thursday save now let's build it now we can see from the output we see our cloned shared library hello darren today is thursday so those are the two parameters that we passed in but that's not such a great thing especially from within the pipeline there may be more intermediate and advanced reasons why you might want to use positional parameters but from a pipeline i have no idea what this first position is because it's not very clear what it would be i would have to go and take a look at this which probably i'd have to take a look anyway but if i was just to mess up and invert these i wouldn't know and then i would say hello thursday today is darren and that would not make any sense so what we're going to do here is we're going to modify our custom step one more time i'm going to change this to a map now i could just say map config but i'm going to go one step further and i'm going to set it to an empty map if i put in the right keystroke there we go and instead of it just being name it's going to be config.name this is where the conventions of maps from groovy apply so we're just saying config dot and we're just going to use dot notation to be able to pull in that parameter and then we'll see how those come into us now this is a very simple example in reality what you should do and i'm not going to go here is i should probably make sure that config.name is not empty i should probably make sure that config.day of week is not empty i probably want to do some extra validation is day of week really a real day of week because i may want to fail the job if you're not passing me valid values i may want to do sanitization on this input lots more steps but for right now this is the simple starting point i'm passing in a map and then i'm going to lift attributes off of the map and use it in my echo statement let's go ahead and save this and let's go back to our pipeline now what we're going to do is modify our pipeline to say name and day of week so just a key value pair but i'm going to mix it up just a little bit i'm going to put my day of week at the front because it's just a map positions do not matter at this point so we see here day of week name darren let's click on save and let's go ahead and do a build now we'll flip back into here and now you can see the output is still hello darren today is thursday so even with the changes to our pipeline by passing in the parameters through a map instead of positionally we're able to make our custom step calls a little more robust so that's it that's a quick overview of how to get started with shared libraries in jenkins but although it was trivial it forms the foundation of everything else you'll be doing in shared libraries in future videos we'll be going into other concepts of how to use shared libraries if this video was helpful for you go ahead and give us a thumbs up and if you haven't subscribed to cloudbees tv yet why not go ahead and click on that subscribe button right now and then ring that bell and that way you'll be notified anytime there are new videos on cloudbees tv thanks for watching and we'll see you in the next video

Channel: CloudBeesTV

Views: 6,809

Rating: 4.9863014 out of 5

Keywords: darin pope, jenkins shared library tutorial, jenkins, devops, github, jenkins tutorial for beginners, jenkins pipeline tutorial, jenkins training, devops tutorial for beginners, introduction to jenkins, introduction to jenkins pipeline

Id: Wj-weFEsTb0

Length: 23min 22sec (1402 seconds)

Published: Thu Jan 21 2021