James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame^] | 1 | :title: GitHub Driver |
| 2 | |
| 3 | GitHub |
| 4 | ====== |
| 5 | |
| 6 | The GitHub driver supports sources, triggers, and reporters. It can |
| 7 | interact with the public GitHub service as well as site-local |
| 8 | installations of GitHub enterprise. |
| 9 | |
| 10 | .. TODO: make this section more user friendly |
| 11 | |
| 12 | Configure GitHub `webhook events |
| 13 | <https://developer.github.com/webhooks/creating/>`_. |
| 14 | |
| 15 | Set *Payload URL* to |
| 16 | ``http://<zuul-hostname>/connection/<connection-name>/payload``. |
| 17 | |
| 18 | Set *Content Type* to ``application/json``. |
| 19 | |
| 20 | Select *Events* you are interested in. See below for the supported events. |
| 21 | |
| 22 | Connection Configuration |
| 23 | ------------------------ |
| 24 | |
| 25 | The supported options in zuul.conf connections are: |
| 26 | |
| 27 | **driver=github** |
| 28 | |
| 29 | **api_token** |
| 30 | API token for accessing GitHub. |
| 31 | See `Creating an access token for command-line use |
| 32 | <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_. |
| 33 | |
| 34 | **webhook_token** |
| 35 | Optional: Token for validating the webhook event payloads. |
| 36 | If not specified, payloads are not validated. |
| 37 | See `Securing your webhooks |
| 38 | <https://developer.github.com/webhooks/securing/>`_. |
| 39 | |
| 40 | **sshkey** |
| 41 | Path to SSH key to use when cloning github repositories. |
| 42 | ``sshkey=/home/zuul/.ssh/id_rsa`` |
| 43 | |
| 44 | **git_host** |
| 45 | Optional: Hostname of the github install (such as a GitHub Enterprise) |
| 46 | If not specified, defaults to ``github.com`` |
| 47 | ``git_host=github.myenterprise.com`` |
| 48 | |
| 49 | Trigger Configuration |
| 50 | --------------------- |
| 51 | GitHub webhook events can be configured as triggers. |
| 52 | |
| 53 | A connection name with the github driver can take multiple events with the |
| 54 | following options. |
| 55 | |
| 56 | **event** |
| 57 | The event from github. Supported events are ``pull_request``, |
| 58 | ``pull_request_review``, and ``push``. |
| 59 | |
| 60 | A ``pull_request`` event will |
| 61 | have associated action(s) to trigger from. The supported actions are: |
| 62 | |
| 63 | *opened* - pull request opened |
| 64 | |
| 65 | *changed* - pull request synchronized |
| 66 | |
| 67 | *closed* - pull request closed |
| 68 | |
| 69 | *reopened* - pull request reopened |
| 70 | |
| 71 | *comment* - comment added on pull request |
| 72 | |
| 73 | *labeled* - label added on pull request |
| 74 | |
| 75 | *unlabeled* - label removed from pull request |
| 76 | |
| 77 | *status* - status set on commit |
| 78 | |
| 79 | A ``pull_request_review`` event will |
| 80 | have associated action(s) to trigger from. The supported actions are: |
| 81 | |
| 82 | *submitted* - pull request review added |
| 83 | |
| 84 | *dismissed* - pull request review removed |
| 85 | |
| 86 | **branch** |
| 87 | The branch associated with the event. Example: ``master``. This |
| 88 | field is treated as a regular expression, and multiple branches may |
| 89 | be listed. Used for ``pull_request`` and ``pull_request_review`` events. |
| 90 | |
| 91 | **comment** |
| 92 | This is only used for ``pull_request`` ``comment`` actions. It accepts a |
| 93 | list of regexes that are searched for in the comment string. If any of these |
| 94 | regexes matches a portion of the comment string the trigger is matched. |
| 95 | ``comment: retrigger`` will match when comments containing 'retrigger' |
| 96 | somewhere in the comment text are added to a pull request. |
| 97 | |
| 98 | **label** |
| 99 | This is only used for ``labeled`` and ``unlabeled`` ``pull_request`` actions. |
| 100 | It accepts a list of strings each of which matches the label name in the |
| 101 | event literally. ``label: recheck`` will match a ``labeled`` action when |
| 102 | pull request is labeled with a ``recheck`` label. ``label: 'do not test'`` |
| 103 | will match a ``unlabeled`` action when a label with name ``do not test`` is |
| 104 | removed from the pull request. |
| 105 | |
| 106 | **state** |
| 107 | This is only used for ``pull_request_review`` events. It accepts a list of |
| 108 | strings each of which is matched to the review state, which can be one of |
| 109 | ``approved``, ``comment``, or ``request_changes``. |
| 110 | |
| 111 | **status** |
| 112 | This is used for ``pull-request`` and ``status`` actions. It accepts a |
| 113 | list of strings each of which matches the user setting the status, the |
| 114 | status context, and the status itself in the format of |
| 115 | ``user:context:status``. For example, |
| 116 | ``zuul_github_ci_bot:check_pipeline:success``. |
| 117 | |
| 118 | **ref** |
| 119 | This is only used for ``push`` events. This field is treated as a regular |
| 120 | expression and multiple refs may be listed. GitHub always sends full ref |
| 121 | name, eg. ``refs/tags/bar`` and this string is matched against the regexp. |
| 122 | |
| 123 | Reporter Configuration |
| 124 | ---------------------- |
| 125 | Zuul reports back to GitHub via GitHub API. Available reports include a PR |
| 126 | comment containing the build results, a commit status on start, success and |
| 127 | failure, an issue label addition/removal on the PR, and a merge of the PR |
| 128 | itself. Status name, description, and context is taken from the pipeline. |
| 129 | |
| 130 | A :ref:`connection<connections>` that uses the github driver must be |
| 131 | supplied to the reporter. It has the following options: |
| 132 | |
| 133 | **status** |
| 134 | String value (``pending``, ``success``, ``failure``) that the reporter should |
| 135 | set as the commit status on github. |
| 136 | ``status: 'success'`` |
| 137 | |
| 138 | **status-url** |
| 139 | String value for a link url to set in the github status. Defaults to the zuul |
| 140 | server status_url, or the empty string if that is unset. |
| 141 | |
| 142 | **comment** |
| 143 | Boolean value (``true`` or ``false``) that determines if the reporter should |
| 144 | add a comment to the pipeline status to the github pull request. Defaults |
| 145 | to ``true``. Only used for Pull Request based events. |
| 146 | ``comment: false`` |
| 147 | |
| 148 | **merge** |
| 149 | Boolean value (``true`` or ``false``) that determines if the reporter should |
| 150 | merge the pull reqeust. Defaults to ``false``. Only used for Pull Request based |
| 151 | events. |
| 152 | ``merge=true`` |
| 153 | |
| 154 | **label** |
| 155 | List of strings each representing an exact label name which should be added |
| 156 | to the pull request by reporter. Only used for Pull Request based events. |
| 157 | ``label: 'test successful'`` |
| 158 | |
| 159 | **unlabel** |
| 160 | List of strings each representing an exact label name which should be removed |
| 161 | from the pull request by reporter. Only used for Pull Request based events. |
| 162 | ``unlabel: 'test failed'`` |