Jenkins: How to create a plugin

Generated by Bing Image Creator

Ah, Jenkins. The venerable old guardian of the CI/CD realm, a tool that has seen the rise and fall of many a software trend, yet stands steadfast — much like that one quirky relative we all have who’s stuck in their ways but somehow indispensable at family gatherings. Jenkins, with its infinite configurability and the charming allure of its plugins is both adored and admonished. It’s the seasoned performer that can pull off any trick in the book, albeit with a rehearsal or two. Jenkins doesn’t just survive in the ever-evolving CI/CD landscape; it thrives, continuing to be a dominant player that commands both respect and a healthy dose of developer memes.

Indeed, the diverse opinions on Jenkins reflect its complexity and versatility in the CI/CD landscape. Amid this backdrop, I’ve contributed into the ecosystem by releasing a Jenkins plugin named pipeline-gcp. In this article I’ll share a high-level overview of the process.

While Jenkins provides comprehensive documentation on plugin creation, navigating through it can be somewhat challenging, as the information is dispersed across various pages. Moreover, sharing insights from a real developer’s experience can be invaluable, especially for first-time contributors looking to make their mark.

Conceptually, there are 3 stages that you will have to go through while creating a plugin: Development, Hosting request and, if accepted, Release.

Development

This phase is perhaps the most extensive yet straightforward part of the plugin creation process. The journey typically begins by setting up an empty project. Jenkins makes this step user-friendly by offering a convenient archetype, which you can initialize with the following Maven command:

mvn -U archetype:generate -Dfilter=io.jenkins.archetypes:

With your project created, the next step is to start actual development. In my experience, the most effective way to figure out what to build — specifically, what Java code to write — is to draw inspiration from existing plugins or to leverage a modern AI tool for guidance. For example, for my plugin I looked to pipeline-aws, a similar plugin designed for AWS. This approach helped me craft the first functional prototype of my plugin.

Next let’s turn our attention to one of the more deceptively challenging aspects of programming: naming. While the archetype efficiently lays the groundwork for your project, it’s essential to adhere to the established naming conventions when choosing the plugin name. Specifically, the artifactId should not include the word plugin, although it’s customary for the repository name to contain it. But if the plugin is accepted into jenkinsci, the repository name will incorporate plugin by default as you can see it in my plugin name at https://github.com/jenkinsci/pipeline-gcp-plugin.

An often overlooked yet critical factor in a plugin’s success is its documentation. For your plugin to be embraced and utilized by the Jenkins community, developers must have clear instructions on its usage. The most effective way to achieve this is by creating a comprehensive and easy-to-understand README file. The importance of this document cannot be overstated: it not only serves as the first point of contact for potential users but also lays the foundation for your plugin’s representation on https://plugins.jenkins.io once released. Therefore, ensure that the README has all the details on how to use the plugin, highlighting its features, setup instructions, and any prerequisites. Remember, a well-documented plugin significantly lowers the entry barrier for new users and increases its potential impact within the community.

As the plugin development progresses, you might ponder on enhancing the user interface, particularly how to incorporate text descriptions or functionalities within the Plugin Manager or Pipeline Syntax views. Jenkins employs Jelly scripting for UI customization in plugins. To add a plugin description visible in the Plugin Manager, you’ll need to include an index.jelly file in the resources directory. Here’s an example structure:

<?jelly escape-by-default='true'?>
<div>
   This plugin adds Jenkins pipeline steps to interact with the GCP API.
</div>

After that the description will be displayed as:

You would also use the same approach to define the pipeline syntax for your plugin functions, particularly for steps that accept parameters. To achieve that you should add config.jelly and help.html files to the resources folder, aligned with the Java class path of the given function. Here’s how you could structure these files:

<?jelly escape-by-default='true'?>
<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:f="/lib/form">
   <f:entry field="credentialsId" title="Credentials Id">
       <f:textbox/>
   </f:entry>
</j:jelly>

<div>
   The id of credentials, presumably stored as Secret file
</div>

Now if you navigate to the Pipeline Syntax view (Jenkins/job/<anyjob>/pipeline-syntax), you should see a proper description and a generated block:

To wrap up the development phase and before submitting the hosting request, it’s crucial to ensure that your plugin meets all necessary quality checks. Execute the following Maven command and make sure it passes:

mvn clean verify package

Jenkins projects typically employ the Spotless plugin to enforce consistent code formatting. Successfully passing this command indicates your code adheres to the required standards and is free from obvious issues.

With all the steps covered, and of course with the actual code implemented and tested, you are now ready to submit a hosting request.

Hosting request

To kick-start the hosting review for your plugin, head over to the repository-permissions-updater and create a new issue, detailing all necessary information. If you’re looking for a point of reference, feel free to draw inspiration from my submission.

The process involves clearing two automated checks — security and hosting — before moving to the manual review by a member of the hosting team. In my experience, this phase was actually quite swift; after addressing the review comments, my hosting request received approval within just two days. Following approval, you’ll be welcomed into the Jenkins organization via email, and your plugin repository will be officially forked into jenkinsci.

Additionally, you’ll be granted owner rights to your repository. This is a perfect time to fine-tune its settings, including merge strategies, pull requests, branch protections, and more, to suit your preferences.

A corresponding permissions file is typically auto-generated in the repository-permissions-updater, although in my case the pipeline was broken (fixed in this PR) so I had to create it manually. This step marks your exciting entry into the vibrant Jenkins community!

However, the journey doesn’t end here. The next step is to release your plugin into the wild, making it available for users worldwide.

Release

Gone are the days when plugin releases were manually executed from local development machines. In a fortunate turn of events, this process has been modernized and is now largely automated through GitHub Actions, with just a few adjustments to the project’s configuration needed:

• Submit a modification to the repository-permissions-updater to enable CD for your plugin.
• Remove release-drafter.yml files
• Add a cd.yml workflow file
• Insert -Dchangelist.format=%d.v%s into the maven.config file
• Remove revision from pom.xml and change changelist to 999999-SNAPSHOT

These adjustments were implemented in my project through a couple of PRs, detailed here and here. For those seeking a more comprehensive explanation, the official Jenkins documentation is an invaluable resource.

Following these modifications with the right labels in place, merging a PR will trigger the release of a new plugin version.

Keep an eye on Artifactory to see your plugin listed, and don’t forget to verify its presence on the Jenkins plugins page. It should only take a few hours to reflect the updates, but in my case there was yet another bug so the waiting time was quite long. It is resolved now, so hopefully you won’t experience anything like that.

Afterwards

Congratulations on successfully releasing your plugin into the Jenkins ecosystem! As you join the ranks of developers enhancing this powerful tool, remember that your efforts help in shaping the future of CI/CD processes. Here’s to many more contributions and continued collaboration within this dynamic community!

Generated by Bing Image Creator