Add help docs

README.md

@@ -38,9 +38,17 @@ If enabled, the statuses will be published in different stages of a Jenkins buil
 - publishChecks: you can publish checks directly in the pipeline script instead of depending on consumer plugins:
 
 ```
-publishChecks name: 'example', title: 'Pipeline Check', summary: 'check through pipeline', text: 'you can publish checks in pipeline script', detailsURL: 'https://github.com/jenkinsci/checks-api-plugin#pipeline-usage'
+publishChecks name: 'example', title: 'Pipeline Check', summary: 'check through pipeline',
+    text: 'you can publish checks in pipeline script',
+    detailsURL: 'https://github.com/jenkinsci/checks-api-plugin#pipeline-usage',
+    actions: [[label:'an-user-request-action', description:'actions allow users to request pre-defined behaviours', identifier:'an unique identifier']]
 ```
 
+To use customized actions, you may need to define them on your own.
+For instance, if you want to add GitHub checks actions which are basically buttons on the checks report,
+you may need to extend [GHEventSubscriber](https://github.com/jenkinsci/github-plugin/blob/master/src/main/java/org/jenkinsci/plugins/github/extension/GHEventsSubscriber.java) to handle the user requests,
+see [the handler](https://github.com/jenkinsci/github-checks-plugin/blob/ea060be67dad522ab6c31444fc4274955ac6e918/src/main/java/io/jenkins/plugins/checks/github/CheckRunGHEventSubscriber.java) for re-run requests as an example.
+
 - withChecks: you can inject the check's name into the closure for other steps to use:
 
 ```

src/main/java/io/jenkins/plugins/checks/steps/PublishChecksStep.java

@@ -3,8 +3,7 @@
 import edu.hm.hafner.util.VisibleForTesting;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import hudson.Extension;
-import hudson.model.Run;
-import hudson.model.TaskListener;
+import hudson.model.*;
 import hudson.util.ListBoxModel;
 import io.jenkins.plugins.checks.api.*;
 import org.apache.commons.lang3.StringUtils;
@@ -229,9 +228,11 @@ ChecksDetails extractChecksDetails() throws IOException, InterruptedException {
     /**
      * A simple wrapper for {@link ChecksAction} to allow users add checks actions by {@link PublishChecksStep}.
      */
-    public static class StepChecksAction implements Serializable {
+    public static class StepChecksAction extends AbstractDescribableImpl<StepChecksAction> implements Serializable {
         private static final long serialVersionUID = 1L;
-        private ChecksAction action;
+        private final String label;
+        private final String identifier;
+        private String description = StringUtils.EMPTY;
 
         /**
          * Creates an instance that wraps a newly constructed {@link ChecksAction} with according parameters.
@@ -243,28 +244,36 @@ public static class StepChecksAction implements Serializable {
          */
         @DataBoundConstructor
         public StepChecksAction(final String label, final String identifier) {
-            action = new ChecksAction(label, StringUtils.EMPTY, identifier);
+            this.label = label;
+            this.identifier = identifier;
         }
 
         @DataBoundSetter
         public void setDescription(final String description) {
-            action = new ChecksAction(getLabel(), description, getIdentifier());
+            this.description = description;
         }
 
         public String getLabel() {
-            return action.getLabel().orElse(StringUtils.EMPTY);
+            return label;
         }
 
         public String getDescription() {
-            return action.getDescription().orElse(StringUtils.EMPTY);
+            return description;
         }
 
         public String getIdentifier() {
-            return action.getIdentifier().orElse(StringUtils.EMPTY);
+            return identifier;
         }
 
         public ChecksAction getAction() {
-            return action;
+            return new ChecksAction(label, description, identifier);
+        }
+
+        /**
+         * Descriptor for {@link StepChecksAction}, required for Pipeline Snippet Generator.
+         */
+        @Extension
+        public static class StepChecksActionDescriptor extends Descriptor<StepChecksAction> {
         }
     }
 }

src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/config.jelly

@@ -0,0 +1,16 @@
+<?jelly escape-by-default='true'?>
+<j:jelly xmlns:j="jelly:core" xmlns:f="/lib/form">
+
+  <f:entry title="Label" field="label">
+    <f:textbox />
+  </f:entry>
+
+  <f:entry title="Identifier" field="identifier">
+    <f:textbox />
+  </f:entry>
+
+  <f:entry title="Description" field="description">
+    <f:textbox />
+  </f:entry>
+
+</j:jelly>

src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-description.html

@@ -0,0 +1,3 @@
+<div>
+    Detailed description for the action's purpose, functionality, and so on.
+</div>

src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-identifier.html

@@ -0,0 +1,5 @@
+<div>
+    The unique identifier for the action. Since for SCM platforms like GitHub, this is the only field that would be
+    sent back to your Jenkins instance when an action is requested, so you may need to use this field to bear more
+    information besides the basic type of the action.
+</div>

src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/StepChecksAction/help-label.html

@@ -0,0 +1,3 @@
+<div>
+    The label to be displayed on the checks report for this action.
+</div>

src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/config.jelly

@@ -29,4 +29,16 @@
     <f:select default="SUCCESS"/>
   </f:entry>
 
+  <f:entry title="${%title.actions}">
+    <div id="actions">
+      <f:repeatableProperty field="actions" add="${%Add Actions}">
+        <f:entry title="">
+          <div align="right">
+            <f:repeatableDeleteButton/>
+          </div>
+        </f:entry>
+      </f:repeatableProperty>
+    </div>
+  </f:entry>
+
 </j:jelly>

src/main/resources/io/jenkins/plugins/checks/steps/PublishChecksStep/config.properties

@@ -5,3 +5,4 @@ title.text=Text
 title.detailsURL=Details URL
 title.status=Status
 title.conclusion=Conclusion
+title.actions=Actions