search

jenkinsci / checks-api-plugin

Jenkins plugin that defines an API for Jenkins to publish checks to SCM platforms.
https://plugins.jenkins.io/checks-api/
MIT License
41 stars 28 forks source link

[doc] How to get started? #210

Closed adamxchen closed 1 year ago

adamxchen commented 1 year ago

Describe your use-case which is not covered by existing documentation.

Hello, bear with me with my limited understanding of this plugin and maybe Jenkins plugin overall, but I am not sure how to get started after installing this plugin on my Jenkins. The consumer guide asks me to write some codes. Where/why do I have to code to make this plugin work? Do you have a Youtube video to instruct how to get started? Thanks in advance.

Also, have a question about the use case. My use case is I have a project, not a pipeline, that is built on Jenkins behind a firewall. Whenever there's a Jenkins build, I want to associate the build with a Github pull request by requesting people manually input it and once the build finishes up, Jenkins can post the build status as Status Check on this PR to either approve or block the merge button. Can I use this plugin for my purpose?

Reference any relevant documentation, other materials or issues/pull requests that can be used for inspiration.

No response

KalleOlaviNiemitalo commented 1 year ago

The consumer guide is relevant if you maintain a Jenkins plugin and want to make that send data to Checks API. If you don't maintain a plugin then it's easier to use one of the known consumers listed in README.md. The Warnings NG plugin can parse compiler messages and forward them via the Checks API and GitHub Checks plugins to GitHub.

I'm not sure this supports "requesting people manually input" the GitHub pull request number.

Re the firewall, if it allows HTTPS requests from the Jenkins controller to GitHub and from users' web browsers to the Jenkins controller, I think it will be OK; the Checks API integration won't need requests from GitHub to the Jenkins controller. Such requests could be useful for automatically triggering builds, but polling or manual triggering works too.

KalleOlaviNiemitalo commented 1 year ago

The data flow via Checks API would be:

  1. Jenkinsfile runs a step such as publishChecks (in Checks API) or recordIssues (in Warnings NG) to send data to Checks API.
  2. Checks API queries the checks publisher plugins that you have installed (including GitHub Checks) and tries to find one that supports the SCM that the run uses.
  3. GitHub Checks receives the data from Checks API and sends it to GitHub.

In addition, Checks API has a "status checks" feature that detects when a Jenkins run starts or finishes, and reports that to the checks publisher plugins, even if the Jenkinsfile doesn't run any checks-related steps. This is implemented in src/main/java/io/jenkins/plugins/checks/status/.

So, you need to install at least the Checks API plugin and the GitHub Checks plugin.

adamxchen commented 1 year ago

@KalleOlaviNiemitalo Thank you so much for the information!

I have one question left.

if it allows HTTPS requests from the Jenkins controller to GitHub and from users' web browsers to the Jenkins controller, I think it will be OK;

I thought the same but in order to use Check API, it requires a Github App which needs a Webhook URL, usually the Jenkins' instance URL. Isn't it blocking us given our Jenkins is private? Can we use a random url for this?

KalleOlaviNiemitalo commented 1 year ago

IIRC the webhook URL is used if you ask GitHub to rerun the checks. I'm not sure it's needed for any other purpose.

adamxchen commented 1 year ago

Thanks for confirming it! We will be using these plugins or implement a new plugin if needed. Closing this issue.