Add reference pipelines file for Github driver

As it has been done for the Pagure driver, include a reference
pipelines section in the Github driver documentation. It helps
the reader to better understand the big picture of the Github's
pipelines configuration but also provide an almost ready to use
pipelines definition file.

Change-Id: Ifb80ab16d23835267eea87fbfef6c3ea1138670b

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

@@ -0,0 +1,118 @@
+- pipeline:
+    name: check
+    description: |
+      Newly uploaded patchsets enter this pipeline to receive an
+      initial check status.
+    manager: independent
+    trigger:
+      github.com:
+        - event: pull_request
+          action:
+            - opened
+            - changed
+            - reopened
+        - event: pull_request
+          action: comment
+          comment: (?i)^\s*recheck\s*$
+    start:
+      github.com:
+        status: 'pending'
+        status-url: "https://zuul.zuul-ci.org/zuul/status.html"
+        comment: false
+    success:
+      github.com:
+        status: 'success'
+      sqlreporter:
+    failure:
+      github.com:
+        status: 'failure'
+      sqlreporter:
+
+- pipeline:
+    name: gate
+    description: |
+      Changes that have been approved by core developers are enqueued
+      in order in this pipeline, and if they pass tests, will be
+      merged.
+    manager: dependent
+    precedence: high
+    supercedes: check
+    require:
+      github.com:
+        review:
+          # Require an approval from user with write access (e.g. core-reviewer)
+          - permission: write
+            type: approved
+        # Require label
+        label: gate
+        open: True
+        current-patchset: True
+    trigger:
+      github.com:
+        - event: pull_request_review
+          action: submitted
+          state: approved
+        - event: pull_request
+          action: comment
+          comment: (?i)^\s*regate\s*$
+        - event: pull_request_review
+          action: submitted
+          state: approved
+        - event: pull_request_review
+          action: dismissed
+          state: request_changes
+        - event: pull_request
+          action: status
+          status: ".*:success"
+        - event: pull_request
+          action: labeled
+          label:
+            - gate
+    start:
+      github.com:
+        status: 'pending'
+        status-url: "https://zuul.zuul-ci.org/zuul/status.html"
+        comment: false
+    success:
+      github.com:
+        status: 'success'
+        merge: true
+        comment: true
+      sqlreporter:
+    failure:
+      github.com:
+        status: 'failure'
+        comment: true
+      sqlreporter:
+    window-floor: 20
+    window-increase-factor: 2
+
+- pipeline:
+    name: post
+    post-review: true
+    description: This pipeline runs jobs that operate after each change is merged.
+    manager: independent
+    precedence: low
+    trigger:
+      github.com:
+        - event: push
+          ref: ^refs/heads/.*$
+    success:
+      sqlreporter:
+    failure:
+      sqlreporter:
+
+- pipeline:
+    name: tag
+    description: This pipeline runs jobs in response to any tag event.
+    manager: independent
+    precedence: high
+    post-review: True
+    trigger:
+      github.com:
+        - event: push
+          ref: ^refs/tags/.*$
+    success:
+      sqlreporter:
+    failure:
+      sqlreporter:

doc/source/reference/drivers/github.rst

@@ -477,3 +477,45 @@ enqueued into the pipeline.
       provided criteria the pull request can not be entered into the
       pipeline.  It follows the same syntax as
       :attr:`pipeline.require.<github source>.review`
+
+Reference pipelines configuration
+---------------------------------
+
+Branch protection rules
+.......................
+
+The rules prevent Pull requests to be merged on defined branches if they are
+not met. For instance a branch might require that specific status are marked
+as ``success`` before allowing the merge of the Pull request.
+
+Zuul provides the attribute tenant.untrusted-projects.exclude-unprotected-branches.
+This attribute is by default set to ``false`` but we recommend to set it to
+``true`` for the whole tenant. By doing so Zuul will benefit from:
+
+ - exluding in-repo development branches used to open Pull requests. This will
+   prevent Zuul to fetch and read useless branches data to find Zuul
+   configuration files.
+ - reading protection rules configuration from the Github API for a given branch
+   to define whether a Pull request must enter the gate pipeline. As of now
+   Zuul only takes in account "Require status checks to pass before merging" and
+   the checked status checkboxes.
+
+With the use of the reference pipelines below, the Zuul project recommends to
+set the minimum following settings:
+
+ - attribute tenant.untrusted-projects.exclude-unprotected-branches to ``true``
+   in the tenant (main.yaml) configuration file.
+ - on each Github repository, activate the branch protections rules and
+   configure the name of the protected branches. Furthermore set
+   "Require status checks to pass before merging" and check the status labels
+   checkboxes (at least ```<tenant>/check```) that must be marked as success in
+   order for Zuul to make the Pull request enter the gate pipeline to be merged.
+
+
+Reference pipelines
+...................
+
+Here is an example of standard pipelines you may want to define:
+
+.. literalinclude:: /examples/pipelines/github-reference-pipelines.yaml
+   :language: yaml