Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction

GitHub-Checks plugin use cases

6 minute readExtensibilityDeveloper productivity

The following use cases demonstrate integrating the GitHub-Checks plugin within CloudBees CD/RO pipelines to perform code linting and displaying the completed run results on your GitHub pull requests (PR). The following pipeline steps are described:

  1. Using the Git plugin Clone procedure to clone a GitHub repository into a workspace.

  2. Using the SonarQube plugin Run Sonar Scan procedure to scan the cloned repository.

  3. Transforming the results of the SonarQube scan into DSL properties using a pipeline Command step.

  4. Using the DSL properties within the GitHub-Checks plugin Create or Update Check Runs procedure as annotations

  5. Running and viewing the GitHub Check run results within a GitHub PR.

Use case prerequisites

The instructions for use cases assume the following tasks have been completed. If they have not, refer to the references provided before starting.

  1. You have completed all required actions described in Configure the GitHub-Checks plugin.

    This use case uses a GitHub-Checks plugin-specific webhook trigger to return runtime property values from the GitHub Checks API. If you have not configured one, you can still perform this use case, but ensure you following the alternate instructions for given Input Parameters.

  2. You have created plugin configurations for the following plugins:

Use the GitHub-Checks plugin for code linting

This section describes the steps to integrate the GitHub-Checks plugin to publish the result of code linting to a GitHub PR. To get started:

  1. In CloudBees CD/RO, navigate to Release Organization  Pipelines.

  2. Select the pipeline you created during Configure the GitHub-Checks plugin.

  3. If the pipeline is new, for Stage 1 select the three dot menu and Details.

    1. If you configured the GitHub App for a pipeline that already existed and had stages, select Create a new stage, and the Details window automatically opens.

  4. Name your stage GitHub Checks code lint, and fill any additional desired fields.

After setting up your pipeline, next add a step using the Git plugin to clone a repository into the workspace.

Clone a repository using the Git plugin

The GitHub-Checks plugin can be used to return results for any GitHub repository configured with your GitHub App integration when performing Install your GitHub App in your repositories.

To clone a repository using the Git plugin:

  1. In your CloudBees CD/RO pipeline GitHub Checks code lint stage, select Add task.

  2. For the task name, enter Clone repo.

  3. Select Define and the Edit Task window opens.

  4. For Task type, select Plugin from the dropdown menu.

  5. In the Search box, enter Clone and select the EC-Git Clone.

    1. Alternately, from the Plugin dropdown menu, select EC-Git, and then select the plugin Procedure  Clone.

  6. Select Input Parameters and provide the parameters for the plugin.

    For the Git repository field, your entry must be a GitHub repository where you installed the GitHub App during Install your GitHub App in your repositories.

  7. Once you have provided the Input parameters, select Save changes.

After configuring your pipeline to clone a GitHub repository, you can configure a step to scan it.

Scan repository using the SonarQube plugin

Because of the open nature of the input parameters for the GitHub-Checks plugin, it is versatile and, when correctly configured, can be used with many third-party tools to perform different analysis types. For this code linting task, the plugin will use results from the SonarQube plugin procedure Run Sonar Scan as GitHub Checks API output.annotations.

To use the SonarQube plugin to scan repository:

  1. In your CloudBees CD/RO pipeline GitHub Checks code lint stage, select Add task.

  2. For the task name, enter Scan repo.

  3. Select Define and the Edit Task window opens.

  4. For Task type, select Plugin from the dropdown menu.

  5. In the Search box, enter Run Sonar Scan and select the EC-SonarQube.

    1. Alternately, from the Plugin dropdown menu, select EC-SonarQube, and then select the plugin Procedure  Run Sonar Scan.

  6. Select Input Parameters and provide the parameters for the plugin.

  7. Once you have provided the Input parameters, select Save changes.

After configuring your pipeline to scan the GitHub repository, you can configure a step to transform the results into DSL properties to use as GitHub Checks API output.annotations and output.annotations.annotation_level.

Transform the scan results into DSL properties

Although the GitHub-Checks plugin allows for manual parameter input for GitHub Checks API output.annotations and output.annotations.annotation_level, the most practical method of using it is to pipe DSL properties from the scan step into the GitHub-Checks plugin. This is done using a Command step in your plugin.

To configure a Command step to return DSL properties:

  1. In your CloudBees CD/RO pipeline GitHub Checks code lint stage, select Add task.

  2. For the task name, enter Transform scan to DSL.

  3. Select Define and the Edit Task window opens.

  4. For Task type, select Command from the dropdown menu, and the Command input fields appear.

  5. For the Command input fields:

    1. For Shell, enter ec-groovy.

    2. For Command, enter:

      import com.electriccloud.client.groovy.ElectricFlow
import com.electriccloud.client.groovy.models.*
import groovy.json.JsonSlurper
import groovy.json.JsonOutput

ElectricFlow ef = new ElectricFlow()
def result = ef.getProperty(propertyName:'/myPipelineRuntime/issueList')?.property?.value
println(result)
def json = new JsonSlurper().parseText(result)
def annotations = []
def annotate = [:]
json.each{
  it ->
  annotate = [path: (String) it.component.split(":")[1], annotation_level: it.severity == 'HIGH' || it.severity == 'MEDIUM' || it.severity == 'BLOCKER' || it.severity == 'MAJOR' || it.severity == 'CRITICAL' ? 'failure' : it.severity == 'MINOR' || it.severity == 'LOW' ? 'warning' : 'notice', message: (String) it.message, start_line: it.startLine, end_line: it.endLine]
  annotations.add(annotate)

}

if($[/javascript (getProperty("/myPipelineRuntime/scanIssue") == null) ? "1":"0"]){
    ef.setProperty(propertyName:'/myPipelineRuntime/scanIssue', value:JsonOutput.toJson(annotations))
}else{
	ef.modifyProperty(propertyName:'/myPipelineRuntime/scanIssue', value:JsonOutput.toJson(annotations))
}
      ▼

      This command returns the $[/myPipelineRuntime/scanIssue] variable, which stores the output.annotations and output.annotations.annotation_level needed by the GitHub-Checks plugin. If you change the $[/myPipelineRuntime/scanIssue] variable name within this code sample, ensure you use your custom variable name when configuring the GitHub-Checks plugin Annotation field.

  6. Once you have provided the Input parameters, select Save changes.

Now that you have a Command step to transform the scan results to DSL properties, you can configure the GitHub-Checks plugin to publish any scan issue results to your GitHub PR.

Create a GitHub Check run

Providing code linting with each GitHub commit can help find common issues, enforce coding standards, and help reduce introducing new known issues. The GitHub-Checks plugin provides this capability by publishing code linting results directly to PRs where developers, reviewers, and QE persons can quickly identify and address newly introduced issues.

To use the SonarQube plugin to scan repository:

  1. In your CloudBees CD/RO pipeline GitHub Checks code lint stage, select Add task.

  2. For the task name, enter Publish scan.

  3. Select Define and the Edit Task window opens.

  4. For Task type, select Plugin from the dropdown menu.

  5. In the Search box, enter Create or Update Check Runs and select the Github-Checks.

    1. Alternately, from the Plugin dropdown menu, select Github-Checks, and then select the plugin Procedure  Create or Update Check Runs.

  6. Select Input Parameters and provide the parameters for the plugin:

    Many of the following entries reference DSL properties from the pipeline webhook. You can use these values or your own custom values.

    1. For Configuration Name, provide the GitHub-Checks plugin configuration you created as part of Configure the GitHub-Checks plugin.

    2. For Commit SHA, enter $[/myPipelineRuntime/parsedWebhookData/sha].

      • If you are not using a GitHub-Checks plugin webhook trigger, you can not use this runtime property. Instead, provide a valid GitHub commit SHA.

    3. For Repository, enter $[/myPipelineRuntime/parsedWebhookData/repository].

      • If you are not using a GitHub-Checks plugin webhook trigger, you can not use this runtime property. Instead, provide a valid GitHub repository where you installed the GitHub-Checks plugin as a GitHub App.

    4. For Installation ID, enter $[/myPipelineRuntime/parsedWebhookData/webhookData/installId].

      • If you are not using a GitHub-Checks plugin webhook trigger, you can not use this runtime property. To find your GitHub App Installation ID, in GitHub, navigate to Settings  Applications. For your GitHub App, select Configure, and the Installation ID is displayed in the page URL.

    5. For Name, provide a GitHub Check run name. If this GitHub Check run doesn’t exist, it is created. If this GitHub Check run already exists, it is updated.

    6. For Status, select Completed.

    7. For Conclusion, select Select None.

      If you select any other option, that will be the conclusion of the check regardless of the results of your code linting scan.

    8. For Title, enter a title for the check run. For example, SonarQube lint check. The output.title field has a maximum length defined in the GitHub Checks API documentation.

    9. For Summary, enter a summary to describe the check run. For example, This check is performed by GitHub App #1234 in CloudBees CD/RO pipeline SonarQube lint GitHub check. The output.summary field has a maximum length defined in the GitHub Checks API documentation.

    10. For Text, provide a description of actions. For example, For a detailed description of error codes, refer to our coding style guide. The output.text field has a maximum length defined in the GitHub Checks API documentation.

    11. For Annotation, enter $[/myPipelineRuntime/scanIssue].

      Here $[/myPipelineRuntime/scanIssue] is used as it was the variable returned for output.annotations and output.annotations.annotation_level from Transform the scan results into DSL properties.

    12. For Result property sheet, you can leave as /myJob/githubChecks or enter a custom value.

  7. Once you have provided the Input parameters, select Save changes.

After configuring your pipeline with the GitHub Check plugin, when you make a new commit on a PR within a repository where the GitHub App is installed, this pipeline should run and publish the result to your PR. You can find this results on your GitHub PR in the Checks tab, similar to:

Shows the result of a GitHub Check run
Figure 1. GitHub Checks run result
Configure the GitHub-Checks plugin
GitHub Checks plugin release notes