diff --git a/README.md b/README.md index a6124c20..68da4904 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,44 @@ [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/XiongKezhi/checks-api-plugin/issues) [![Jenkins](https://ci.jenkins.io/job/Plugins/job/github-checks-plugin/job/master/badge/icon?subject=Jenkins%20CI)](https://ci.jenkins.io/job/Plugins/job/github-checks-plugin/job/master/) [![GitHub Actions](https://github.com/jenkinsci/github-checks-plugin/workflows/CI/badge.svg?branch=master)](https://github.com/jenkinsci/github-checks-plugin/actions) +[![Codacy Badge](https://app.codacy.com/project/badge/Grade/2c7fa67496a743778ca60cc9604212d2)](https://www.codacy.com/gh/jenkinsci/github-checks-plugin?utm_source=github.com&utm_medium=referral&utm_content=jenkinsci/github-checks-plugin&utm_campaign=Badge_Grade) +[![codecov](https://codecov.io/gh/jenkinsci/github-checks-plugin/branch/master/graph/badge.svg)](https://codecov.io/gh/jenkinsci/github-checks-plugin) +![GitHub Checks Plugin Cover](docs/images/github-checks-plugin-cover.png) -This a [Google Summer of Code](https://summerofcode.withgoogle.com/) project for [Jenkins Organization](https://www.jenkins.io/), it is still under development. +This plugin publishes checks to GitHub through [GitHub Checks API](https://docs.github.com/en/rest/reference/checks#runs). +It implements the extension points defined in [Checks API Plugin](https://github.com/jenkinsci/checks-api-plugin). -## Useful links: -* [Project Idea](https://www.jenkins.io/projects/gsoc/2020/project-ideas/github-checks/) -* [Project Design](https://docs.google.com/document/d/1hVQTd9jKw0sx8JQR8KjbM-7lWW84e2vFjmmkzBpBbSk/edit?usp=sharing) -* [Meeting Notes](https://docs.google.com/document/d/1TZLmu3nBPbwUjzLVYGnV_YtYvmzxzw6A4eEVYpbmi3Y/edit?usp=sharing) +This plugin has been installed, alone with the [General API Plugin](https://github.com/jenkinsci/checks-api-plugin) on [ci.jenkins.io](https://ci.jenkins.io/Plugins) to help maintain over 1500 Jenkins plugins. You can take a look at the [action](https://github.com/jenkinsci/github-checks-plugin/runs/1025018883) for this repository or other plugin repositories under [Jenkins organization](https://github.com/jenkinsci) for the results. +## Features + +*Prerequsite: only GitHub App with proper permissions can publish checks, this [guide](https://github.com/jenkinsci/github-branch-source-plugin/blob/master/docs/github-app.adoc) helps you authenticate your Jenkins as a GitHub App.* + +### Build Status Check + +![GitHub Status](docs/images/github-status.png) + +By listening to the Jenkins builds, this plugin will automatically publish statuses (pending, in progress, and completed) to GitHub. + +*Note: If you are using [GitHub Branch Source Plugin](https://github.com/jenkinsci/github-branch-source-plugin), it will also send status notifications to GitHub through [Status API](https://docs.github.com/en/rest/reference/repos#statuses). +You can disable it by using [Disable GitHub Multibranch Status Plugin](https://github.com/jenkinsci/disable-github-multibranch-status-plugin) or [Skip Notification Trait Plugin](https://github.com/jenkinsci/skip-notifications-trait-plugin).* + +### Rerun Failed Build + +![Failed Checks](docs/images/failed-checks.png) + +If your Jenkins build failed, a failed check will be published here. +A "Re-run" button will be added automatically by GitHub, by clicking it, you can schedule a new build for the **last** commit of this branch. + +## Contributing + +Refer to our [contribution guidelines](https://github.com/jenkinsci/.github/blob/master/CONTRIBUTING.md) + +## Acknowledgements + +This plugin was started as a [Google Summer of Code 2020 project](https://summerofcode.withgoogle.com/projects/#5139745388101632), special thanks to the support from [Jenkins GSoC SIG](https://www.jenkins.io/sigs/gsoc/) and the entire community. + +## LICENSE + +Licensed under MIT, see [LICENSE](LICENSE) \ No newline at end of file diff --git a/doc/activity.puml b/doc/activity.puml deleted file mode 100644 index 35232b23..00000000 --- a/doc/activity.puml +++ /dev/null @@ -1,37 +0,0 @@ -@startuml -|GitHub| -start -:New PR/Commit; -|Jenkins Instance| -:A job enters the queue; -|GitHub Checks API Plugin| -:Enumerate consumers to -create check runs in "queued"; -|GitHub| -:Create check runs; -stop - -|Jenkins Instance| -start -:The related job starts; -|GitHub Checks API Plugin| -:Enumerate consumers to -update check runs to "in -progress"; -|GitHub| -:Update check runs; -stop - -|Jenkins Instance| -start -:The related job completes; -|GitHub Checks API Plugin| -:Enumerate consumers to -complete check runs with -warnings, annotations, etc.; -|GitHub| -:Complete check runs -and display warnings, -annotations, etc.; -end -@enduml \ No newline at end of file diff --git a/doc/classes-design.puml b/doc/classes-design.puml deleted file mode 100644 index 4a2904ee..00000000 --- a/doc/classes-design.puml +++ /dev/null @@ -1,67 +0,0 @@ -@startuml -interface ExtensionPoint #LightBlue -class QueueLitener #LightBlue -class RunListener #LightBlue -class Run #LightBlue -interface RunAction2 #LightBlue - -class GitHubAppCredentials #TECHNOLOGY { - String generateAppInstallationToken() -} - -class GHEventSubscriber #LightPink - -class JobListener #BUSINESS { - void onEnterWaiting() - void onStart() - void onComplete() -} -class CheckGHEventSubscriber #BUSINESS -class CheckRunResultAction #BUSINESS { - long id - CheckRunResult result - CheckRunAction(long id, CheckRunResult result) - long getId() - CheckRunResult getResult() - static List all() -} -abstract class CheckRunResult #BUSINESS { - String getName() - Output getOutput() - Annotation getAnnotation() -} - -class CheckRunResultImpl1 #LightGray -class CheckRunResultImpl2 #LightGray -class CheckRunResultImpl3 #LightGray - - -JobListener .right.> CheckRunResultAction -JobListener .> CheckRunResult -JobListener -up-|> QueueLitener -JobListener -up-|> RunListener -JobListener .down.> GitHubAppCredentials -JobListener .left.> CheckGHEventSubscriber - -CheckGHEventSubscriber -up-|> GHEventSubscriber - -CheckRunResultAction "*" -right-> "1" Run -CheckRunResultAction "1" --> "1" CheckRunResult -CheckRunResultAction .up.|> RunAction2 - -CheckRunResult .right.|> ExtensionPoint -CheckRunResultImpl1 -up-|> CheckRunResult -CheckRunResultImpl2 -up-|> CheckRunResult -CheckRunResultImpl3 -up-|> CheckRunResult - -skinparam legendBackgroundColor white -legend -|= |= Class Owners | -| | GitHub Checks API Plugin | -| | Jenkins Core | -| | GitHub Branch Source Plugin | -| | Consumers plugins | -| | GitHub Plugin | -endlegend - -@enduml \ No newline at end of file diff --git a/doc/component-design.puml b/doc/component-design.puml deleted file mode 100644 index 0747eb2e..00000000 --- a/doc/component-design.puml +++ /dev/null @@ -1,34 +0,0 @@ -@startuml - -skinparam componentStyle uml2 - -component [codingstyle] #beige -component [github-checks-api] #lightGreen -component [github] #lightBlue -component [github-branch-source] #lightBlue -component [github-api] #lightBlue -component [jackson2-api] #lightBlue -component [plugin-util-api] #lightBlue - -[github-checks-api] .up.> [codingstyle] -[github-checks-api] .left.> [plugin-util-api] -[github-checks-api] .right.> [jackson2-api] -[github-checks-api] ..> [github-branch-source] -[github-checks-api] ..> [github-api] -[github-checks-api] ..> [github] - -[plugin-util-api] .up.> [codingstyle] -[github-branch-source] .> [github] -[github] ..> [github-api] -[github-branch-source] ..> [github-api] - -skinparam legendBackgroundColor white -legend -|= |= Module type | -| | GitHub Checks API Plugin | -| | Jenkins Plugins | -| | Java Libraries | - -endlegend - -@enduml \ No newline at end of file diff --git a/docs/images/coverage-checks.png b/docs/images/coverage-checks.png new file mode 100644 index 00000000..e26fd34b Binary files /dev/null and b/docs/images/coverage-checks.png differ diff --git a/docs/images/failed-checks.png b/docs/images/failed-checks.png new file mode 100644 index 00000000..a407a6c4 Binary files /dev/null and b/docs/images/failed-checks.png differ diff --git a/docs/images/github-checks-plugin-cover.png b/docs/images/github-checks-plugin-cover.png new file mode 100644 index 00000000..c6047e8a Binary files /dev/null and b/docs/images/github-checks-plugin-cover.png differ diff --git a/docs/images/github-status.png b/docs/images/github-status.png new file mode 100644 index 00000000..7b2b61f9 Binary files /dev/null and b/docs/images/github-status.png differ diff --git a/docs/images/warning-checks.png b/docs/images/warning-checks.png new file mode 100644 index 00000000..4225430e Binary files /dev/null and b/docs/images/warning-checks.png differ