CORE-STEPS.md

Introduction

Many Jenkins plugins add builders or post-build actions (collectively, build steps) for use in freestyle and similar projects. (Jenkins core also adds a few of these, though most have been split off into their own plugins or could be split off.)

In many cases these build steps would be valuable to use from workflows, but it would be overkill to define a separate Workflow-only step. Therefore selected build steps can be called directly from workflows.

Syntax

As an example, you can write a flow:

node {
    sh 'make something'
    step([$class: 'ArtifactArchiver', artifacts: 'something'])
}

Here we are running the standard Archive the artifacts post-build action (hudson.tasks.ArtifactArchiver), and configuring the Files to archive property (artifacts) to archive our file something produced in an earlier step. The easiest way to see what class and field names to use is to examine the config.xml of a freestyle project doing the same thing:

  <publishers>
    <hudson.tasks.ArtifactArchiver>
      <artifacts>something</artifacts>
      <latestOnly>false</latestOnly>
      <allowEmptyArchive>false</allowEmptyArchive>
    </hudson.tasks.ArtifactArchiver>
  </publishers>

You can generally omit miscellaneous fields (like latestOnly here) and they will be left at their default values.

Currently supported steps

• hudson.tasks.ArtifactArchiver (example above)
• hudson.tasks.Fingerprinter
• hudson.tasks.junit.JUnitResultArchiver
• hudson.tasks.JavadocArchiver
• hudson.tasks.Mailer

Interacting with build status

Builders generally have a simple mode of operation: they run, and either pass or fail. So you can call these at any point in your flow.

Post-build actions (also known as publishers) are divided into two classes:

• Recorders like the JUnit publisher add something to the build, and might affect its status.
• Notifiers like the mailer cannot affect the build’s status, though they may behave differently depending on its status.

When a recorder is run from a flow, it might set the build’s status (for example to unstable), but otherwise is likely to work intuitively. Running a notifier is trickier since normally a flow in progress has no status yet, unlike a freestyle project whose status is determined before the notifier is called. To help interoperate better with these, you can use the catchError step:

node {
    catchError {
        sh 'might fail'
    }
    step([$class: 'Mailer', recipients: 'admin@somewhere'])
}

If its body fails, the flow build’s status will be set to failed, so that subsequent notifier steps will see that this build is failed. In the case of the mail sender, this means that it will send mail. (It may also send mail if this build succeeded but previous ones failed, and so on.)

In the future some important publishers may get dedicated Workflow steps, so that you could use a more flexible idiom:

node {
    try {
        sh 'might fail'
        mail subject: 'all well', recipients: 'admin@somewhere'
    } catch (e) {
        mail subject: "failed with #{e.message}", recipients: 'admin@somewhere'
        throw e
    }
}

though this would not automatically adjust the message according to the status of previous builds as the standard mail notifier does.

Adding support from plugins

As a plugin author, to add support for use of your build step from a workflow, depend on Jenkins 1.577+ (tips). Then implement SimpleBuildStep, following the guidelines in its Javadoc. Also prefer @DataBoundSetters to a sprawling @DataBoundConstructor (tips).