New API in Pipeline: API Plugin 2.34 that allows Pipeline steps to track more detailed status/result information

[Devin Nusbaum]

Pipeline: API 2.34 added a new API called WarningAction that allows steps to report irregular but non-fatal events that occurred during their execution while allowing Pipeline execution to continue normally. This allows long-standing and highly-voted issues such as JENKINS-39203 to be fixed by modifying Pipeline steps that change the build result directly to also use the new API so that visualizations such as Blue Ocean use the new API (through Pipeline: Graph Analysis 1.10) to display more specific statuses. For any maintainers of plugins setting the build result directly today, here is some information to help you understand how to use the new API if you would like to do so.

First, if you have a step that throws an exception today to indicate failure, that's totally fine, keep doing that! The new API only applies to steps that want to indicate some kind of problem but continue normal Pipeline execution.

For regular Steps, if you have code in a StepExecution that does something like this and want to use the new API:

  getContext().get(Run.class).setResult(...);

Keep setting the build result the same way and add code to add a WarningAction to the current FlowNode like this:

  getContext().get(Run.class).setResult(...);

  getContext().get(FlowNode.class).addOrReplaceAction(new WarningAction(...).withMessage(...));

The result you pass to the WarningAction constructor will determine how Blue Ocean displays your step and the stage or parallel branch enclosing your step. The message is optional and may be visualized directly in Blue Ocean in some prominent way in the future, but for now it is not shown anywhere.

See this pull request to JUnit plugin for an example of how to integrate a plugin with the new API (in particular the changes to JUnitResultsStepExecution.java). 

If your plugin currently uses SimpleBuildStep or SimpleBuildWrapper to implement a step that can be used in Freestyle and Pipeline jobs, there is no way to use the new API directly, and you need to create a new Pipeline Step to be able to use the new API. You should be able to call the SimpleBuildStep from your new Step to avoid duplicating logic, but unfortunately you will need to duplicate getters and setters to make data-binding work correctly for the step. Here is an in-progress PR to Warnings Next Generation Plugin that shows what this kind of change might look like.

See UnstableStep.java for an example of a new step that uses the new API.

Thanks, and let me know if you have any questions!

Devin

[Mark Waite]

Would you be willing to add this information to the "Writing Pipeline Compatible Plugins" page on jenkins.io?  It seems like a very useful addition to the documentation on that page.

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/4cd76eee-f788-40b2-98a1-51c1172113ec%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Thanks!

Mark Waite

[Devin Nusbaum]

Good idea! I wasn’t sure of the right location to document this, but that link looks like a good start. Looking through the related links I think the Writing Pipeline Steps or Core Steps documentation could also use some related updates. I’ll add a task to my TODO list to update them.

To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAO49JtEy77cQXeXXCiqVTO_zcbszp3iS40zLMDEMq%2BmtFCFZcg%40mail.gmail.com.