Some time ago I published a post in which I explain how you can create credentials in Jenkins. It’s very important topic because there are several ways to manage the credentials, but not all of them are safe. I showed you in my post how to use Credential Plugin, and it’s enough for adding, storing and managing secrets, but not for using them in the builds. I think this topic should have a separate discussion, so I decided to make this post. So now you will learn how to use credentials in Jenkins projects!
One can add and manage credentials by the Credential Plugin. It stores the secrets in encrypted forms, so – in theory – no one will know the stored passwords and tokens. It is possible to pass on the password in the project as the parameter, but it is not recommended. The parameter of type “password” is only masked by the HTML input type “password”. Also, it is not stored globally – if you have many projects which require the same username/password pair, you must define the same parameters with the same values in the every one of them.
But how can you pass on your credentials to the job? The simplest way is using the Credentials Binding Plugin. It allows you to binds your credentials to environmental variables, so then you can easily attach them to your builds.
Credentials in Jenkins projects – more details
First, you need to install the plugin – you can do it with the Plugin Manager. More details about this addon are available on the plugin Wiki page. After installation, every project will have an additional checkbox in the “Build Environment” section, named “Use secret text(s) or file(s)”. It should look like here:
After you select this checkbox, the new section will appear under the “Build Environment” – “Bindings”. It’s exactly the place, where you bind your previously created credentials. It can be added one or more bindings of the following types:
- certificate – Java Keystore with the certificate/certificates chain,
- docker client certificate – requires Docker Commons Plugin,
- secret ZIP file – ZIP archive with the credentials,
- secret file – file with credentials,
- secret text – some tokens or other chains,
- username and password (conjoined) – username and password in the one variable,
- username and password (separated) – username and password in the two variables.
Every of these types has its own, short help available after the question mark pressing. You can add one or more credentials, also with the mixed type:
Of course, you can choose only these credentials, which you have previously created. So if you don’t remember/don’t know how you can create and store credentials in Jenkins, please visit my post, in which I explained this topic. Since you have some credentials and you want to bind them, you can simply name the individual variables. In the example above, I chose two types of secrets: secret file and username and password (separated). As you can see, I had to fill in some fields, which correspond to the right parts of the credentials.
I have bound credentials – what now?
So, for now, you have some credentials stored in the Jenkins, and you have created some bindings. Now I will show you how you can pass on your work to the project. Let’s assume that you want to run a PowerCLI script which lists all of the VMs in the vCenter Server. Look at this code:
# Connect to vCenter Server
Connect-VIServer vcs1.lab.local -User $env:viuser -Password $env:vipassword
# Rest of the script
Here, I passed the credentials with the “$env:” prefixes. This is not always the right way. First I will show you another example, and then I will try to explain to you when you should use which one of them. So let’s assume I want to send an e-mail with the swaks (Swiss Army Knife for SMTP – I really like this tool!). In this case, the code would look like this:
# muser = variable with mail user (username and password separated)
# mpass = variable with mail password (username and password separated)
swaks -t firstname.lastname@example.org -f email@example.com \
-s mail.example.com:587 -tls -a LOGIN -au $muser -ap $mpass
But, wait… Where are the “$env:” prefixes? They’re gone! To be honest, they’re not gone, but they’re not necessary here. In other words – it depends on the plugin. Under the appropriate Build Step, you can find a link to the available environment variables. These variables are different for each Plugin. So you should check the scheme of the variables in your steps everywhen you want to use credentials in Jenkins projects. For example here is a fragment from the PowerShell available variables:
Thanks to Jeff who commented on this post, this is a clarification of this topic:
Jenkins exports environment variables consistently, but you access them according to the scripting language in use. So in your shell script smtp example, an environment variable “foo” can be directly accessed with “$foo”. But in PowerShell, environment variables are accessed by using the expression parser, syntax “$env:foo”.
And there is a place, where you can find the link to the variables:
You should build your bindings according to the scheme. If the list informs you that every variable starts with some prefix, you need to use this prefix with your credential variables.