blob: cc2a5c982353d275087bdb972f99e930c5f2200a [file] [log] [blame]
James E. Blaireff5a9d2017-06-20 00:00:37 -07001:title: GitHub Driver
2
3GitHub
4======
5
6The GitHub driver supports sources, triggers, and reporters. It can
7interact with the public GitHub service as well as site-local
8installations of GitHub enterprise.
9
10.. TODO: make this section more user friendly
11
12Configure GitHub `webhook events
13<https://developer.github.com/webhooks/creating/>`_.
14
15Set *Payload URL* to
16``http://<zuul-hostname>/connection/<connection-name>/payload``.
17
18Set *Content Type* to ``application/json``.
19
20Select *Events* you are interested in. See below for the supported events.
21
22Connection Configuration
23------------------------
24
25The 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
49Trigger Configuration
50---------------------
51GitHub webhook events can be configured as triggers.
52
53A connection name with the github driver can take multiple events with the
54following options.
55
56**event**
57The event from github. Supported events are ``pull_request``,
58``pull_request_review``, and ``push``.
59
60A ``pull_request`` event will
61have 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
79A ``pull_request_review`` event will
80have 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**
87The branch associated with the event. Example: ``master``. This
88field is treated as a regular expression, and multiple branches may
89be listed. Used for ``pull_request`` and ``pull_request_review`` events.
90
91**comment**
92This is only used for ``pull_request`` ``comment`` actions. It accepts a
93list of regexes that are searched for in the comment string. If any of these
94regexes matches a portion of the comment string the trigger is matched.
95``comment: retrigger`` will match when comments containing 'retrigger'
96somewhere in the comment text are added to a pull request.
97
98**label**
99This is only used for ``labeled`` and ``unlabeled`` ``pull_request`` actions.
100It accepts a list of strings each of which matches the label name in the
101event literally. ``label: recheck`` will match a ``labeled`` action when
102pull request is labeled with a ``recheck`` label. ``label: 'do not test'``
103will match a ``unlabeled`` action when a label with name ``do not test`` is
104removed from the pull request.
105
106**state**
107This is only used for ``pull_request_review`` events. It accepts a list of
108strings each of which is matched to the review state, which can be one of
109``approved``, ``comment``, or ``request_changes``.
110
111**status**
112This is used for ``pull-request`` and ``status`` actions. It accepts a
113list of strings each of which matches the user setting the status, the
114status 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**
119This is only used for ``push`` events. This field is treated as a regular
120expression and multiple refs may be listed. GitHub always sends full ref
121name, eg. ``refs/tags/bar`` and this string is matched against the regexp.
122
123Reporter Configuration
124----------------------
125Zuul reports back to GitHub via GitHub API. Available reports include a PR
126comment containing the build results, a commit status on start, success and
127failure, an issue label addition/removal on the PR, and a merge of the PR
128itself. Status name, description, and context is taken from the pipeline.
129
130A :ref:`connection<connections>` that uses the github driver must be
131supplied to the reporter. It has the following options:
132
133**status**
134String value (``pending``, ``success``, ``failure``) that the reporter should
135set as the commit status on github.
136``status: 'success'``
137
138**status-url**
139String value for a link url to set in the github status. Defaults to the zuul
140server status_url, or the empty string if that is unset.
141
142**comment**
143Boolean value (``true`` or ``false``) that determines if the reporter should
144add a comment to the pipeline status to the github pull request. Defaults
145to ``true``. Only used for Pull Request based events.
146``comment: false``
147
148**merge**
149Boolean value (``true`` or ``false``) that determines if the reporter should
150merge the pull reqeust. Defaults to ``false``. Only used for Pull Request based
151events.
152``merge=true``
153
154**label**
155List of strings each representing an exact label name which should be added
156to the pull request by reporter. Only used for Pull Request based events.
157``label: 'test successful'``
158
159**unlabel**
160List of strings each representing an exact label name which should be removed
161from the pull request by reporter. Only used for Pull Request based events.
162``unlabel: 'test failed'``