Checks API Plugin

Inspired by the GitHub Checks API, this plugin aims to provide a general API to allow Jenkins plugins publishing checks (or reports) to remote source code management (SCM) platforms (e.g. GitHub, GitLab, BitBucket, etc.).

By consuming this API, other plugins can publish check with customized parameters for a Jenkins build, such as status, summary, warnings, code annotations, or even images. Implementations of this API decide on how to make use of these parameters and where to publish the checks.

Known consumers:

• Warnings Next Generation Plugin
• Code Coverage API Plugin
• JUnit Plugin - since 1.39
• xUnit Plugin - since 3.1.0
• Autograding Plugin

Implementations:

• GitHub Checks Plugin
• Gitea Checks Plugin

This plugin, along with its GitHub implementation, has been installed on ci.jenkins.io to help maintain over 1500 Jenkins plugins. You can take a look at the action for this repository or other plugin repositories under Jenkins organization for the results.

Embedded Features

Build Status Check

This plugin defines extension points to publish statuses to different SCM platforms.

It depends on the implementation to decide whether to skip them and what name to use.

If enabled, the statuses will be published in different stages of a Jenkins build (enters the queue, checkout, and completes).

Pipeline Usage

• 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',
    actions: [[label:'an-user-request-action', description:'actions allow users to request pre-defined behaviours', identifier:'an unique identifier']]

To use customized actions, you will need to write a Jenkins plugin. If you want to add GitHub checks actions, which are basically buttons on the checks report, you need to extend GHEventSubscriber to handle the event, see the handler for re-run requests as an example.

• withChecks: you can inject the check's name into the closure for other steps to use:

withChecks('injected name') {
    // some other steps that will extract the name
}

withChecks will publish an in progress check immediately and then other consuming plugins will publish the final check.

You can also include the checks stage name with includeStage:

withChecks(name: 'Tests', includeStage: true) {
    sh 'mvn -Dmaven.test.failure.ignore=true clean verify'
    junit '**/target/surefire-reports/TEST-*.xml'
}

Combining includeStage with the JUnit plugin works well to publish checks for each test suite:

Example full pipeline with parallel stages

def axes = [
        platforms: ['linux', 'windows'],
        jdks: [17, 21],
]
def builds = [:]
axes.values().combinations {
    def (platform, jdk) = it
    builds["${platform}-jdk${jdk}"] = {
        node(platform) {
            stage("${platform.capitalize()} - JDK ${jdk} - Test") {
                checkout scm
                withChecks(name: 'Tests', includeStage: true) {
                    sh 'mvn -Dmaven.test.failure.ignore=true clean verify'
                    junit '**/target/surefire-reports/TEST-*.xml'
                }
            }
        }
    }
}

parallel builds

Guides

• Consumers Guide
• Implementation Guide

Contributing

Refer to our contribution guidelines

Acknowledgements

This plugin was started as a Google Summer of Code 2020 project, special thanks to the support from Jenkins GSoC SIG and the entire community.

LICENSE

Licensed under MIT, see LICENSE