figshare is a platform where users can upload and share images, graphs, presentations and other documents. These artifacts can be generated using different tools - including Jenkins. The BioUno figshare Plug-in integrates Jenkins and figshare. The figshare API uses OAuth 1.0, and requires data such as client key, client secret, token key and token secret stored in Jenkins.
What the Jenkins Credentials Plug-in does, basically, is store these credentials in a way that it is both safer and easier to maintain in Jenkins. Before that, users would add passwords as parameters in jobs or store credentials globally in Jenkins via plug-ins. This resulted in security problems, and was also difficult to maintain with a high number of jobs with different credentials.
This blog post written by Stephen Connolly when the plug-in was open sourced by CloudBees will tell you more about why the plug-in was created, and also contains a more complete description.
The Credentials Plug-in API per example
The Wiki of the Credentials Plug-in contains a good starting point for plug-in developers. Having a working example can be useful too - the Wiki page lists several implementations.
For the figshare Plug-in, we have used the Rally Plug-in as example. This post describes our process of learning how to use the Credentials Plug-in. Hopefully it will be useful for other plug-in developers doing the same thing.
Adding Maven dependency
The first step is to add the credentials-plugin to our
pom.xml, so that we can use the API.
We are using the latest and greatest version.
Implementing the Credentials interface
The Credentials interface defines the basic contract for the credentials. It defines what kind of information the credentials hold. In our case, it will have a client key, a client secret, a token key and a token secret.
Then we can implement our
@NameWith annotation defines a name provider for this credential. This name provider is used by the user interface to list the credentials by name.
@DataBoundConstructor annotation is used by Stapler to bind the user interface parameters to the Java properties.
@Extension is for the descriptor of our credential. The display name of the descriptor of a credential is used as the kind of credentials.
The name provider used in the first is quite simple.
When the user have to pick a credential, the name provider will display the name of the credential in Jenkins (not the display name).
These are the classes that we need to write specifically for the Credentials Plug-in. Next we will add the Jelly views, that display forms in the Jenkins UI to create these objects, and finally some more Java code that is related to the credentials, but in the Notifier (the extension point used for the figshare Plug-in).
The Jelly files are used to create forms and contribute to the Jenkins user interface. It is XML but also contains several helper tags. Our Jelly form for the credentials,
FigShareOAuthCredentialsImpl/config.jelly, contains the following code.
If you look at our constructor with
@DataBoundConstructor, you will notice where the parameters in the constructor come from.
How to use credentials in a Notifier/Publisher
A Notifier is a type of Publisher, that sends information to another system. Publisher is an extension point in Jenkins, called after build steps, exactly for publishing data (graphs, reports, artefacts, results, etc) to other entities.
This is the extension point that we used for the figshare Plug-in.
The first change is that the constructor of the notifier must be prepared to receive a
credentialsId, which the user will select out of a combo.
The code inside the constructor after a comment is responsible for calling
CredentialsProvider to look up for certain types of credentials. These credentials are assumed to have already been created. It is simply looking for the credential with the ID equals to the given
Once the credential has been created, we can later use it to interact with figshare in another part of the code.
There is, however, one more change required in the Descriptor of the Notifier. You must include a
doFillCredentialsIdItems method, which will return a list of credentials. This list is used in the job configuration, to let the user select one.
And here is how the
config.jelly of the notifier looks like.
<c:select/> is a special tag, provided by the Credentials Plug-in, that will call your
doFillCredentialsIdItems method to fill a combo box with credentials ID’s for the user to pick one.
That is all for today. We hope you find it useful and will enjoy using the plug-in. It is being released this weekend as 0.1 to our update center.