[CDash] GitHub Status API support

[Zack Galbreath]

On Thu, Apr 4, 2019 at 9:57 AM Cristian Morales Vega <
christian.morales.vega at gmail.com> wrote:

> I see the PR has already been merged. I guess I could take the latest
> Docker Hub image and just try it? Not sure of the exact steps needed,
> though.
>
> Do I need to add a Webhook to my GitHub repository? Just push or any
> event? What does happen when CDash receives the POST request from
> GitHub? Since in my setup right now Jenkins is basically in charge of
> everything and CDash doesn't really know about anything until it
> receives the results from Jenkins I'm unsure how all the pieces fit
> together.
>

Yes, this feature is now available.

I was going to write up a blog post announcing it & how to use it, but we
would also like to add support for GitHub Checks, so I'm going to hold off
on official publication until that's ready too.

But since you asked, here's how to get CDash to post statuses on your
GitHub commits.

Step 1: Register a GitHub App
<https://developer.github.com/apps/building-github-apps/creating-a-github-app/>
for
your CDash instance.
You can skip this step if you're using a public, Kitware hosted CDash
instance like open.cdash.org.
Here's what to enter for the various fields on this form.

   - Homepage URL: the base URL of your CDash installation (
   http://open.cdash.org)
   - User authorization callback URL: user.php on this CDash instance (
   https://open.cdash.org/user.php)
   - Setup URL: leave blank
   - Redirect on update: leave unchecked
   - Webhook URL: /api/v1/noop.php (https://open.cdash.org/api/v1/noop.php).
   This will need to be updated to our new GitHub webhook API endpoint once
   our support for "GitHub Checks" is ready.
   - Webhook secret: leave blank for now

Permissions:

   - Repository contents: read only (to be able to compare commits)
   - Commit statuses: read and write (this is the main feature we're after)
   - You might also want to give it read & write permissions for Checks
   now, just so you don't have to update it later once this feature is ready.

For now leave "User Permissions" and "Subscribe to events" blank.
Update a logo, we recommend cdash.png in the public/img folder.

For "Where can this GitHub App be installed?", we recommend "any account"
depending on who will be submitting to this CDash.

Now you can finally click "Create GitHub app". Record your APP ID. this
will go in your config.local.php file as $CDASH_GITHUB_APP_ID. Also
generate a private key and upload this to config/github.pem.


Step 2: Install the app on your repository / organization.
>From https://github.com/settings/apps/<my-app-name> click the "Install App"
link in the sidebar and follow the instructions. This will give you an
installation ID.


Step 3: Add the installation ID to your CDash project

   - Login to CDash as a project admin.
   - Navigate to Settings -> Project -> Repository
   - Make sure your project's GitHub URL is filled in under the Repository
   field.
   - Input your installation ID under the "username" field



Step 4: update your builds to specify a "status context" (example here
<https://github.com/Kitware/CDash/blob/master/.circleci/ctest_driver_script.cmake>
)

The idea here is that you might not necessarily want every single build of
a commit to be publishing its status to GitHub. So we make this feature
opt-in on a per-build basis. This also gives us the opportunity to specify
a context for this build, so we can differentiate between multiple builds
posting status on a single commit. Rather than adding another CTest
variable to hold this information, we decided to use the relatively new
"build properties" feature in CDash. This allows you to upload arbitrary
key/value pairs (in JSON format) that will be associated with a build.

When testing CDash itself on CircleCI we do two builds, one for MySQL and
one for Postgres. Here's an example of what this looks like on GitHub
<https://github.com/Kitware/CDash/pull/821> (click the green checkmark on
the last commit)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/cdash/attachments/20190405/aaedb2c8/attachment-0001.htm>