How to use Jenkins plugins in Jenkins Pipeline

Pipeline and plugins

Jenkins Pipeline is a suite of plugins which supports implementing and integrating continuous delivery pipelines into Jenkins.

Not all Jenkins plugins are compatible with Jenkins Pipeline (check

With “old” Jenkins plugins installation and usage is straightforward. But it’s not true for Jenkins Pipeline. Even if you find a plugin which is compatible with Jenkins Pipeline, it’s not always obvious how to use it in Jenkinsfile.

How to use Jenkins plugins in Jenkinsfile

There are different ways to identify how to use a Jenkins plugin in Jenkinsfile.

Easy way #1

Easiest way is when plugin maintainer makes the Jenkins plugin compatible with Jenkins Pipeline and includes an example of usage directly on plugin wiki page.

Few examples of plugins which have Jenkins Pipeline support examples on wiki pages:

Easy way #2

We can use snippet generator from Jenkins.

Snippet generator

Hard way

It’s harder when you find that plugin is compatible with Jenkins Pipeline in document, but there’re no examples of how to use it in Jenkins Pipeline.

To succeed with this task we need to have a background of what makes Jenkins plugin compatible with Jenkins Pipeline. Such information can be found in workflow-step-api-plugin repository file.

The most important parts for us are:

Extend Step. Define mandatory parameters in a @DataBoundConstructor. Define optional parameters using @DataBoundSetter. (Both need matching getters.)

Extend StepDescriptor. Besides a display name, pick a function name which will be used from Groovy scripts.

Build steps and post-build actions in Jenkins core as of 2.2, and in some plugins according to their individual changelogs, have defined symbols which allow for a more concise syntax. Snippet Generator will offer this when available.

  node {
    sh 'make something'
    archiveArtifacts 'something'

Also, we need to refer to Jenkins Pipeline plugin steps:

See the user documentation for background. The metastep is step. To add support for use of a Builder or Publisher from a pipeline, depend on Jenkins 1.577+, typically 1.580.1 (tips). Then implement SimpleBuildStep, following the guidelines in its Javadoc. Also, prefer @DataBoundSetters to a sprawling @DataBoundConstructor.

From the documentation is clear what we should look for in Jenkins plugin source code to find out how to execute it as a Jenkins Pipeline step.

  • STEP_CLASS_NAME (check example from below)
    • find a class in plugin repository which extends from SimpleBuildStep
  • STEP_PARAMETERS (check example from below)
    • check constructor marked with @DataBoundConstructor annotation for mandatory step parameters
    • check methods marked with @DataBoundSetter annotation
  • STEP_FUNCTION_NAME (check example from below)
    • check for @Symbol annotation on top of descriptor class

This should be enough to call plugin step from Jenkinsfile:




Let’s take JaCoCo as an example (we made sure first that plugin is compatible with Jenkins Pipeline). We navigate to plugin source code and try to find required information.

  • Class which extends from SimpleBuildStep

    public class JacocoPublisher extends Recorder implements SimpleBuildStep {
  • Parameters

    • DataBoundConstructor without parameters which sets defaults

      public JacocoPublisher() {
          this.execPattern = "**/**.exec";
          this.classPattern = "**/classes";
          this.sourcePattern = "**/src/main/java";
          this.inclusionPattern = "";
          this.exclusionPattern = "";
          this.skipCopyOfSrcFiles = false;
          this.minimumInstructionCoverage = "0";
          this.minimumBranchCoverage = "0";
          this.minimumComplexityCoverage = "0";
          this.minimumLineCoverage = "0";
          this.minimumMethodCoverage = "0";
          this.minimumClassCoverage = "0";
          this.maximumInstructionCoverage = "0";
          this.maximumBranchCoverage = "0";
          this.maximumComplexityCoverage = "0";
          this.maximumLineCoverage = "0";
          this.maximumMethodCoverage = "0";
          this.maximumClassCoverage = "0";
          this.changeBuildStatus = false;
          this.deltaInstructionCoverage = "0";
          this.deltaBranchCoverage = "0";
          this.deltaComplexityCoverage = "0";
          this.deltaLineCoverage = "0";
          this.deltaMethodCoverage = "0";
          this.deltaClassCoverage = "0";
          this.buildOverBuild = false;
    • List of DataBoundSetter’s

      public void setExecPattern(String execPattern) {
          this.execPattern = execPattern;
      public void setClassPattern(String classPattern) {
          this.classPattern = classPattern;
      public void setSourcePattern(String sourcePattern) {
          this.sourcePattern = sourcePattern;
      public void setInclusionPattern(String inclusionPattern) {
          this.inclusionPattern = inclusionPattern;
      public void setExclusionPattern(String exclusionPattern) {
          this.exclusionPattern = exclusionPattern;
    • Symbol annotation with function name

      @Extension @Symbol("jacoco")
      public static class DescriptorImpl extends BuildStepDescriptor<Publisher> {

Now when we found all the required information, we can start using JaCoCo Publisher step in Jenkins Pipeline:

  • via step class name

    step([$class: 'JacocoPublisher',
          classPattern: '**/classes',
          sourcePattern: '**/src/main/java'])
  • via step function name

    jacoco execPattern:'**/**.exec', classPattern: '**/classes', sourcePattern: '**/src/main/java'])

Few more examples

Few more examples of Jenkins plugins which are compatible with Jenkins Pipeline, but don’t provide usage steps:

  • ArtifactsArchiver
    • From source code:

      public class ArtifactArchiver extends Recorder implements SimpleBuildStep {
      @DataBoundConstructor public ArtifactArchiver(String artifacts) {
         this.artifacts = artifacts.trim();
         allowEmptyArchive = false;
      @Extension @Symbol("archiveArtifacts")
      public static class DescriptorImpl extends BuildStepDescriptor<Publisher> {
    • In Jenkinsfile:

      step([$class: 'ArtifactArchiver', artifacts:'someFile.txt'])


      archiveArtifacts artifacts: 'someFile.txt'
  • ArtifactArchiverStep (yes, 2nd archiver :confused: )
    • From source code:

      public class ArtifactArchiverStep extends AbstractStepImpl {
      public ArtifactArchiverStep(String includes) {
          this.includes = includes;
      public static class DescriptorImpl extends StepDescriptor {
          public String getFunctionName() {
              return "archive";
          public String getDisplayName() {
              return "Archive artifacts";
    • In Jenkinsfile:

      archive artifacts: 'someFile.txt'

      Since class ArtifactArchiverStep extends AbstractStepImpl and not extends SimpleBuildStep we can’t use following syntax:

      step([$class: 'ArtifactArchiverStep', artifacts:'someFile.txt'])

      and following exception will be thrown:

      java.lang.UnsupportedOperationException: no known implementation of interface jenkins.tasks.SimpleBuildStep is named ArtifactArchiverStep

      Step resolving happens in DescribableModel#resolveClass method.

  • HockeyappRecorder
    • From source code:

      public class HockeyappRecorder extends Recorder implements SimpleBuildStep {
      public HockeyappRecorder(List<HockeyappApplication> applications, boolean debugMode,
                               BaseUrlHolder baseUrlHolder, boolean failGracefully) {
          this.applications = applications;
          this.debugMode = debugMode;
          this.baseUrlHolder = baseUrlHolder;
          if (baseUrlHolder != null) {
              this.baseUrl = baseUrlHolder.baseUrl;
          this.failGracefully = failGracefully;

      Constructor takes an array of HockeyApplication objects

      public HockeyappApplication(String apiToken, String appId, boolean notifyTeam,
                                  String filePath, String dsymPath, String libsPath,
                                  String tags, String teams, boolean mandatory,
                                  boolean downloadAllowed,
                                  OldVersionHolder oldVersionHolder,
                                  RadioButtonSupport releaseNotesMethod,
                                  RadioButtonSupport uploadMethod) {
          this.schemaVersion = SCHEMA_VERSION_NUMBER;
          this.apiToken = Util.fixEmptyAndTrim(apiToken);
          this.appId = Util.fixEmptyAndTrim(appId);
          this.notifyTeam = notifyTeam;
          this.filePath = Util.fixEmptyAndTrim(filePath);
          this.dsymPath = Util.fixEmptyAndTrim(dsymPath);
          this.libsPath = Util.fixEmptyAndTrim(libsPath);
          this.tags = Util.fixEmptyAndTrim(tags);
          this.downloadAllowed = downloadAllowed;
          this.oldVersionHolder = oldVersionHolder;
          this.releaseNotesMethod = releaseNotesMethod;
          this.uploadMethod = uploadMethod;
          this.teams = Util.fixEmptyAndTrim(teams);
          this.mandatory = mandatory;
    • In Jenkinsfile:

      step([$class: 'HockeyappRecorder',
            applications: [[apiToken: 'token123', downloadAllowed: true,
                            filePath: 'file123', mandatory: false, notifyTeam: true,
                            releaseNotesMethod: [$class: 'ChangelogReleaseNotes'],
                            uploadMethod: [$class: 'AppCreation', publicPage: false]]],
            debugMode: false, failGracefully: false])

      As there is no Symbol and no function name provided for the descriptor in this is the only way to call HockeyappRecorder step.

We learned how Jenkins Pipeline works with Jenkins plugins and how to use them in Jenkinsfile. With the help of the community :pray:, we can increase coverage of plugins compatibility with Jenkins Pipeline.

comments powered by Disqus