Recent Blog Posts

This blog post is about our phase 3 progress on GitHub Checks API Project, you can find our previous blog posts for phase 1 and phase 2. At the end of this summer, the GSoC journey for GitHub Checks API Project comes to an end as well. In this blog post, I’ll show you our works during the last month: Pipeline Support Rerun Request Support Git SCM Support Documentation All the above features will be available in our planned 1.0.0 version of Checks API Plugin and GitHub Checks Plugin. Coding Phase 3 Demo Pipeline Support The pipeline support allows users to directly publish checks in their pipeline script without depending on any other consumers. The check in the above screenshot is published by script: publishChecks name: 'pipeline check', title: 'pipeline ', summary: '# A pipeline check example', text: "## This check is published through the pipeline script", detailsURL: 'https://ci.jenkins.io' If you want to publish checks to GitHub, please install the GitHub implementation and refer to the GitHub API documentation for the requirements for each field. A default value (build link) for detailsURL will be provided automatically. This feature can be useful when many stages exist in your pipeline script and each takes a long time: you can publish a check for each stage to keep track of the build. Rerun Request Support The rerun request allows GitHub users to rerun the failed builds. When a build failed (which leads to a failed check), a Re-run button will be added automatically by GitHub. By clicking the Re-run button, Jenkins will reschedule a build for the last commit of this branch. Since all checks of a commit are produced by a single build, you don’t have to rerun all failed checks, just rerun any one of the failed check will refresh all checks. Git SCM Support Thanks to Ullrich 's great help, the GitHub Checks Plugin now supports Git SCM. This means now you can publish checks for your freestyle project or any other projects that use Git SCM. Document Consumers Guide and Implementation Guide are now available. As a Jenkins developer, you can now start consuming our API or even providing an implementation for other SCM platforms beside GitHub. Acknowledgment The whole GitHub Checks API project is started as a Google Summer of Code project. Much appreciate my mentors ( Tim and Ullrich) for their great help during the whole summer. Also huge thanks to the Jenkins GSoC SIG and the whole community for the technique support and resources. Resources Checks API Plugin GitHub Checks Plugin Project Page Gitter Channel

Another great coding phase for GitHub Checks API Project ends! In this phase, we focused on consuming the checks API in two widely used plugins: Warnings NG Plugin Code Coverage API Plugin Besides the external usage, we have also split the general checks API from its GitHub implementation and released both of the plugins: Checks API Plugin GitHub Checks Plugin Coding Phase 2 Demo [starts from 25:20] Warning Checks The newly released Warnings NG plugin 8.4.0 will use checks API to publish different check runs for different static analysis tools. Without leaving GitHub, users are now able to see the analysis report they interested in. On GitHub’s conversation tab for each PR, users will see summaries for those checks like the screenshot above. The summaries will include: The status that indicates the quality gate The name of the analysis tool used A short message that indicates statistics of new and total issues More fine-grained statistics can be found in the Details page. Another practical feature is the annotation for specific lines of code. Users can now review the code alone with the annotations. Try It In Wanings NG plugin 8.4.0, the warning checks is set as a default feature only for GitHub. For other SCM platforms, a NullPublisher will be used which does nothing. Therefore, you can get those checks for your own GitHub project just in a few steps: Update Warnings NG plugin to 8.4.0 Install GitHub Checks plugin on your Jenkins instance Follow the GitHub app authentication guide to configure the credentials for the multi-branch project or GitHub organization project you are going to use Use warnings-ng plugin in your Jenkinsfile for the project you configured in the last step, e.g. node { stage ('Checkout') { checkout scm } stage ('Build and Static Analysis') { sh 'mvn -V -e clean verify -Dmaven.test.failure.ignore' recordIssues tools: [java(), javaDoc()], aggregatingResults: 'true', id: 'java', name: 'Java' recordIssues tool: errorProne(), healthy: 1, unhealthy: 20 recordIssues tools: [checkStyle(pattern: 'target/checkstyle-result.xml'), spotBugs(pattern: 'target/spotbugsXml.xml'), pmdParser(pattern: 'target/pmd.xml'), cpd(pattern: 'target/cpd.xml')], qualityGates: [[threshold: 1, type: 'TOTAL', unstable: true]] } } For more about the pipeline usage of warnings-ng plugin, please see the official documentation. However, if you don’t want to publish the warnings to GitHub, you can either uninstall the GitHub Checks plugin or disable it by adding skipPublishingChecks: true. recordIssues enabledForFailure: true, tools: [java(), javaDoc()], skipPublishingChecks: true Coverage Checks The coverage checks are achieved by consuming the API in Code Coverage API plugin. First, in the conversation tab of a PR, users will be able to see the summary about the coverage difference compared to previous builds. The Details page will contain some other things: Links to the reference build, including the target branch build from the master branch and the last successful build from this branch Coverage healthy score (the default value is 100% if the threshold is not configured) Coverages and trends of different types in table format The pull request for this feature will soon be merged and will be included in the next release of Coverage Checks API plugin. After that, you can use it by adding the below section to your pipeline script: node { stage ('Checkout') { checkout scm } stage ('Line and Branch Coverage') { publishCoverage adapters: [jacoco('**/*/jacoco.xml')], sourceFileResolver: sourceFiles('STORE_ALL_BUILD') } } Like the warning checks, you can also disable the coverage checks by setting the field skipPublishingChecks, e.g. publishCoverage adapters: [jacoco('**/*/jacoco.xml')], sourceFileResolver: sourceFiles('STORE_ALL_BUILD'), skipPublishingChecks: true Next Phase In the next phase, we will turn our attention back to Checks API Plugin and GitHub Checks Plugin and add the following features in future versions: Pipeline Support Users can publish checks directly in a pipeline script without requiring a consumer plugin that supports the checks. Re-run Request Users can re-run Jenkins build through Checks API. Lastly, it is exciting to inform that we are currently making the checks feature available on ci.jenkins.io for all plugins hosted in the jenkinsci GitHub organization, please see INFRA-2694 for more details. Resources Checks API Plugin GitHub Checks Plugin Project Page Gitter Channel

This blog post is about our coding phase 1 progress on GSoC project: GitHub Checks API Plugin. The GitHub Checks API is a highly customized way to integrate CI tools to make reports for pull-requests (PRs). It allows users to see CI reports on GitHub pages directly. Figure 1. GitHub Check Run Screenshot from GitHub Docs What’s more exciting is that it can leave annotations on specific lines of code, just as the comments people left while reviewing. Figure 2. Check Run Annotation Screenshot from GitHub Docs While on Jenkins' side, the source code view provided by Warnings Next Generation Plugin does pretty much the same thing. Figure 3. Source Code View from Warnings Next Generation Plugin Utilizing such features through GitHub Checks API, it would make Jenkins more convenient to GitHub users. Features from Coding Phase 1 In the past month, our team was mostly working on the general checks API and an implementation for GitHub checks API. GitHub Checks API Plugin Demo [starts from 50:15] General Checks API Although the general checks API is developed based on the semantic meaning of GitHub Checks API, we still want to prepare it for similar concepts on other platforms like Commit Status API from GitLab. Contributions for implementations on these platforms will be welcomed in the future. GitHub Checks API Implementation Our work on supporting GitHub Checks API is mostly done by now. Besides, we implemented a consumer to automatically create a check run that simply indicates the current stage of a Jenkins build. After the release, Jenkins developers (especially publisher plugin ones) can create their own GitHub checks for a GitHub branch source project by consuming our API. Example: To create a check run like: Consumers need to use our API in this way: ChecksDetails details = new ChecksDetailsBuilder() .withName("Jenkins") .withStatus(ChecksStatus.COMPLETED) .withDetailsURL("https://ci.jenkins.io") .withStartedAt(LocalDateTime.now(ZoneOffset.UTC)) .withCompletedAt(LocalDateTime.now(ZoneOffset.UTC)) .withConclusion(ChecksConclusion.SUCCESS) .withOutput(new ChecksOutputBuilder() .withTitle("Jenkins Check") .withSummary("# A Successful Build") .withText("## 0 Failures") .withAnnotations(Arrays.asList( new ChecksAnnotationBuilder() .withPath("Jenkinsfile") .withLine(1) .withAnnotationLevel(ChecksAnnotationLevel.NOTICE) .withMessage("say hello to Jenkins") .withStartColumn(0) .withEndColumn(20) .withTitle("Hello Jenkins") .withRawDetails("a simple echo command") .build(), new ChecksAnnotationBuilder() .withPath("Jenkinsfile") .withLine(2) .withAnnotationLevel(ChecksAnnotationLevel.WARNING) .withMessage("say hello to GitHub Checks API") .withStartColumn(0) .withEndColumn(30) .withTitle("Hello GitHub Checks API") .withRawDetails("a simple echo command") .build())) .build()) .withActions(Collections.singletonList( new ChecksAction("formatting", "format code", "#0"))) .build(); ChecksPublisher publisher = ChecksPublisherFactory.fromRun(run); publisher.publish(details); Future Works The next step is integrating our API into Warnings Next Generation Plugin and Code Coverage API Plugin consume our API. After that, pipeline support will be added: users can publish checks directly in a pipeline script without requiring a consumer plugin that support the checks. Resources GitHub Repository Project Page Gitter Channel References GitHub Doc: Creating CI tests with the Checks API Warnings Next Generation Plugin: Source Code View

This blogpost was updated to reflect the general availability of the feature after the release of GitHub Branch Source 2.7.1 on April 26th, 2020. I’m excited to announce support for authenticating as a GitHub app in Jenkins. This has been a long awaited feature by many users. It has been released in GitHub Branch Source 2.7.1 which is now available in the Jenkins update centers. Authenticating as a GitHub app brings many benefits: Larger rate limits - The rate limit for a GitHub app scales with your organization size, whereas a user based token has a limit of 5000 regardless of how many repositories you have. User-independent authentication - Each GitHub app has its own user-independent authentication. No more need for 'bot' users or figuring out who should be the owner of 2FA or OAuth tokens. Improved security and tighter permissions - GitHub Apps offer much finer-grained permissions compared to a service user and its personal access tokens. This lets the Jenkins GitHub app require a much smaller set of privileges to run properly. Access to GitHub Checks API - GitHub Apps can access the the GitHub Checks API to create check runs and check suites from Jenkins jobs and provide detailed feedback on commits as well as code annotation Getting started Install the GitHub Branch Source plugin, make sure the version is 2.7.1 or above. Configuring the GitHub Organization Folder Follow the GitHub App Authentication setup guide. These instructions are also linked from the plugin’s README on GitHub. Once you’ve finished setting it up, Jenkins will validate your credential and you should see your new rate limit. Here’s an example on a large org: How do I get an API token in my pipeline? In addition to usage of GitHub App authentication for Multi-Branch Pipeline, you can also use app authentication directly in your Pipelines. You can access the Bearer token for the GitHub API by just loading a 'Username/Password' credential as usual, the plugin will handle authenticating with GitHub in the background. This could be used to call additional GitHub API endpoints from your pipeline, possibly the deployments api or you may wish to implement your own checks api integration until Jenkins supports this out of the box. Note: the API token you get will only be valid for one hour, don’t get it at the start of the pipeline and assume it will be valid all the way through Example: Let’s submit a check run to Jenkins from our Pipeline: pipeline { agent any stages{ stage('Check run') { steps { withCredentials([usernamePassword(credentialsId: 'githubapp-jenkins', usernameVariable: 'GITHUB_APP', passwordVariable: 'GITHUB_ACCESS_TOKEN')]) { sh ''' curl -H "Content-Type: application/json" \ -H "Accept: application/vnd.github.antiope-preview+json" \ -H "authorization: Bearer ${GITHUB_ACCESS_TOKEN}" \ -d '{ "name": "check_run", \ "head_sha": "'${GIT_COMMIT}'", \ "status": "in_progress", \ "external_id": "42", \ "started_at": "2020-03-05T11:14:52Z", \ "output": { "title": "Check run from Jenkins!", \ "summary": "This is a check run which has been generated from Jenkins as GitHub App", \ "text": "...and that is awesome"}}' https://api.github.com/repos/ / /check-runs ''' } } } } } What’s next GitHub Apps authentication in Jenkins is a huge improvement. Many teams have already started using it and have helped improve it by giving pre-release feedback. There are more improvements on the way. There’s a proposed Google Summer of Code project: GitHub Checks API for Jenkins Plugins. It will look at integrating with the Checks API, with a focus on reporting issues found using the warnings-ng plugin directly onto the GitHub pull requests, along with test results summary on GitHub. Hopefully it will make the Pipeline example below much simpler for Jenkins users :) If you want to get involved with this, join the GSoC Gitter channel and ask how you can help.