How to use credentials in Jenkins projects?

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!

Short reminder

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:

credentials in Jenkins projects

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 certificaterequires 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.

Types of credentials in Jenkins

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:

Credentials in Jenkins - binding example

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:

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:

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:

PowerShell 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:

Shell build step Jenkins

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.

8 Replies to “How to use credentials in Jenkins projects?”

  1. A clarification on the environment variables – 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”. This is why you see different ways of accessing the environment variable after Jenkins exports it.

    1. Thank you very much Jeff! I let myself add a part of your comment to post, of course with a notice that it’s your comment. 🙂 Thanks to this more people can read your clarification. But if you mind, I will remove that part – just let me know!

  2. Hi Emil,
    Thanks for posting detailed explanation. Is there any specific format for “Secret File” to store credentials?
    Please share if you have thoughts on secret file.

    1. Hi, Karthi!

      Thanks for your reply. As far as I know, there is no just only one specific format for “secret file” – it depends on what you need. The secret file is represented by the path to this file in a Jenkins filesystem. So if there is an application which needs a secret file (in theory it can be an SSL/SSH certificate or something like that), you can use “secret file” credential and deliver that in a secure way. 🙂

  3. Hi,
    How to use $credential = get-credential in powershell script, and than run thad script with Jenkins.

    And pass that $credential parameter into Jenkins

    1. Hi,

      I’m not sure whether I understand you well. Do you mean that you have credentials stored somewhere on disk or something similar? Or do you have an external script which you want to run in Jenkins, previously downloading it from the repository?

      You should be able to use “credential binding” functionality for almost every idea you will find. If you run an external PowerShell script, you should pass a variable with a credential as an argument and it should work (but I have not made any tests).

  4. I am pulling the db password from the server using Jenkins job and storing in environment variable in one of the stage in Jenkins pipeline and in another stage I can able to connect the app server with the stored environment variable as password successfully but the password is displayed as plain text on Jenkins console,I want to mask the password on Jenkins console(I don’t want to manually update password as CredentialsId, passwords are dynamically pull from remote server) .Can someone please let me know how i can achieve it. Thanks

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.