Doc updates for Github interaction

This updates a few things that have come up when using Github with
Zuul

* The use "github" for the reference pipeline for consistency with
  everything else.

* No need to set the status-url after
  If5c5fa3c8b33b349d95eb52175e4faf17f5bbb36

* Switch the example pipelines to use the check API, rather than the
  older status API.  Comments are left in the reference pipeline to
  show both, depending on what a project prefers.

* Add the check_run trigger event to examples, which is emitted when a
  failed run has it's "Re-Run" button pushed in the checks UI page.

* Add a note on the Depends-On: format for Github, because if you're
  used to Gerrit where the Depends-On: works in the change description
  always you may not realise you have to update the PR description.

Change-Id: I049e801c5a36666367db8f9e4fa4cb59b5f08933

doc/source/discussion/gating.rst

@@ -253,7 +253,15 @@ on a GitHub pull request (PR #4) might have the following footer::
 
   Depends-On: https://github.com/example/test/pull/4
 
-And a change which depends on a Gerrit change (change number 3)::
+.. note::
+
+   For Github the ``Depends-On:`` footer must be in the *Pull Request*
+   description, which is separate and often different to the commit
+   message (i.e. the text submitted with ``git commit``).  This is in
+   contrast to Gerrit where the change description is always the
+   commit message.
+
+A change which depends on a Gerrit change (change number 3)::
 
   Depends-On: https://review.example.com/3
 

doc/source/examples/pipelines/github-reference-pipelines.yaml

@@ -5,27 +5,48 @@
       initial check status.
     manager: independent
     trigger:
-      github.com:
+      github:
+        # Run this pipeline on new/changed pull requests
         - event: pull_request
           action:
             - opened
             - changed
             - reopened
+        # Run in response to a pull request comment "recheck"
         - event: pull_request
           action: comment
           comment: (?i)^\s*recheck\s*$
+        # When using the checks API to report results, failed runs
+        # will have a "re-run" button which emits this event.
+        - event: check_run
     start:
-      github.com:
-        status: 'pending'
-        status-url: "https://zuul.zuul-ci.org/zuul/status.html"
+      github:
+        check: 'in_progress'
         comment: false
+        # It is recommended to use the checks API for consistency with
+        # other common CI tools that integrate with Github.  Results
+        # will appear on the "checks" tab of PR and changes.  There is
+        # generally no need to have Zuul leave comments when using the
+        # checks API.
+        #
+        # The older status API appears inline with the PR and can be
+        # enabled by uncommenting the "status:" in the various
+        # sections below.  You should choose one or the other
+        # depending on project preferences.
+        #
+        #status: 'pending'
+        #comment: false
     success:
-      github.com:
-        status: 'success'
+      github:
+        check: 'success'
+        comment: false
+        #status: 'success'
       sqlreporter:
     failure:
-      github.com:
-        status: 'failure'
+      github:
+        check: 'failure'
+        comment: false
+        #status: 'failure'
       sqlreporter:
 
 - pipeline:
@@ -38,7 +59,7 @@
     precedence: high
     supercedes: check
     require:
-      github.com:
+      github:
         review:
           # Require an approval from user with write access (e.g. core-reviewer)
           - permission: write
@@ -48,7 +69,7 @@
         open: True
         current-patchset: True
     trigger:
-      github.com:
+      github:
         - event: pull_request_review
           action: submitted
           state: approved
@@ -69,20 +90,22 @@
           label:
             - gate
     start:
-      github.com:
-        status: 'pending'
-        status-url: "https://zuul.zuul-ci.org/zuul/status.html"
+      github:
+        check: 'in_progress'
         comment: false
+        #status: 'pending'
     success:
-      github.com:
-        status: 'success'
+      github:
+        check: 'success'
+        comment: false
+        #status: 'success'
         merge: true
-        comment: true
       sqlreporter:
     failure:
-      github.com:
-        status: 'failure'
-        comment: true
+      github:
+        check: 'failure'
+        #status: 'failure'
+        comment: false
       sqlreporter:
     window-floor: 20
     window-increase-factor: 2
@@ -94,7 +117,7 @@
     manager: independent
     precedence: low
     trigger:
-      github.com:
+      github:
         - event: push
           ref: ^refs/heads/.*$
     success:
@@ -109,7 +132,7 @@
     precedence: high
     post-review: True
     trigger:
-      github.com:
+      github:
         - event: push
           ref: ^refs/tags/.*$
     success:

doc/source/howtos/github_setup.rst

@@ -151,16 +151,17 @@ following contents:
            - event: pull_request
              action: comment
              comment: (?i)^\s*recheck\s*$
+           - event: check_run
        start:
          github:
-           status: pending
+           check: 'in_progress'
            comment: false
        success:
          github:
-           status: 'success'
+           check: 'success'
        failure:
          github:
-           status: 'failure'
+           check: 'failure'
 
 Merge that commit into the repository.