10 KiB
- title
-
GitHub Driver
GitHub
The GitHub driver supports sources, triggers, and reporters. It can interact with the public GitHub service as well as site-local installations of GitHub enterprise.
Configure GitHub webhook events.
Set Payload URL to
http://<zuul-hostname>/connection/<connection-name>/payload
.
Set Content Type to application/json
.
Select Events you are interested in. See below for the supported events.
Connection Configuration
There are two forms of operation. Either the Zuul installation can be configured as a Github App or it can be configured as a Webhook.
If the Github App
approach is taken, the config settings app_id
and
app_key
are required. If the Webhook approach is taken, the
api_token
setting is required.
The supported options in zuul.conf connections are:
driver=github
- app_id
-
App ID if you are using a GitHub App. Can be found under the "Public Link" on the right hand side labeled "ID".
app_id=1234
- app_key
-
Path to a file containing the Secret Key Zuul will use to create tokens for the API interactions. In Github this is known as "Private key" and must be collected when generated.
app_key=/etc/zuul/github.key
- api_token
-
API token for accessing GitHub if Zuul is configured with Webhooks. See Creating an access token for command-line use.
- webhook_token
-
Required token for validating the webhook event payloads. In the GitHub App Configuration page, this is called "Webhook secret". See Securing your webhooks.
- sshkey
-
Path to SSH key to use when cloning github repositories.
sshkey=/home/zuul/.ssh/id_rsa
- server
-
Optional: Hostname of the github install (such as a GitHub Enterprise) If not specified, defaults to
github.com
server=github.myenterprise.com
- canonical_hostname
-
The canonical hostname associated with the git repos on the GitHub server. Defaults to the value of server. This is used to identify projects from this connection by name and in preparing repos on the filesystem for use by jobs. Note that Zuul will still only communicate with the GitHub server identified by server; this option is useful if users customarily use a different hostname to clone or pull git repos so that when Zuul places them in the job's working directory, they appear under this directory name.
canonical_hostname=git.example.com
Trigger Configuration
GitHub webhook events can be configured as triggers.
A connection name with the github driver can take multiple events with the following options.
- event
-
The event from github. Supported events are
pull_request
,pull_request_review
, andpush
.A
pull_request
event will have associated action(s) to trigger from. The supported actions are:opened - pull request opened
changed - pull request synchronized
closed - pull request closed
reopened - pull request reopened
comment - comment added on pull request
labeled - label added on pull request
unlabeled - label removed from pull request
status - status set on commit
A
pull_request_review
event will have associated action(s) to trigger from. The supported actions are:submitted - pull request review added
dismissed - pull request review removed
- branch
-
The branch associated with the event. Example:
master
. This field is treated as a regular expression, and multiple branches may be listed. Used forpull_request
andpull_request_review
events. - comment
-
This is only used for
pull_request
comment
actions. It accepts a list of regexes that are searched for in the comment string. If any of these regexes matches a portion of the comment string the trigger is matched.comment: retrigger
will match when comments containing 'retrigger' somewhere in the comment text are added to a pull request. - label
-
This is only used for
labeled
andunlabeled
pull_request
actions. It accepts a list of strings each of which matches the label name in the event literally.label: recheck
will match alabeled
action when pull request is labeled with arecheck
label.label: 'do not test'
will match aunlabeled
action when a label with namedo not test
is removed from the pull request. - state
-
This is only used for
pull_request_review
events. It accepts a list of strings each of which is matched to the review state, which can be one ofapproved
,comment
, orrequest_changes
. - status
-
This is used for
pull-request
andstatus
actions. It accepts a list of strings each of which matches the user setting the status, the status context, and the status itself in the format ofuser:context:status
. For example,zuul_github_ci_bot:check_pipeline:success
. - ref
-
This is only used for
push
events. This field is treated as a regular expression and multiple refs may be listed. GitHub always sends full ref name, eg.refs/tags/bar
and this string is matched against the regexp.
Reporter Configuration
Zuul reports back to GitHub via GitHub API. Available reports include a PR comment containing the build results, a commit status on start, success and failure, an issue label addition/removal on the PR, and a merge of the PR itself. Status name, description, and context is taken from the pipeline.
A connection<connections>
that uses the github
driver must be supplied to the reporter. It has the following
options:
- status
-
String value (
pending
,success
,failure
) that the reporter should set as the commit status on github.status: 'success'
- status-url
-
String value for a link url to set in the github status. Defaults to the zuul server status_url, or the empty string if that is unset.
- comment
-
Boolean value (
true
orfalse
) that determines if the reporter should add a comment to the pipeline status to the github pull request. Defaults totrue
. Only used for Pull Request based events.comment: false
- merge
-
Boolean value (
true
orfalse
) that determines if the reporter should merge the pull reqeust. Defaults tofalse
. Only used for Pull Request based events.merge=true
- label
-
List of strings each representing an exact label name which should be added to the pull request by reporter. Only used for Pull Request based events.
label: 'test successful'
- unlabel
-
List of strings each representing an exact label name which should be removed from the pull request by reporter. Only used for Pull Request based events.
unlabel: 'test failed'
Requirements Configuration
As described in pipeline.require <pipeline-require>
and pipeline.reject <pipeline-reject>
, pipelines may
specify that items meet certain conditions in order to be enqueued into
the pipeline. These conditions vary according to the source of the
project in question. To supply requirements for changes from a GitHub
source named my-github, create a congfiguration such as the
following:
pipeline:
require:
my-github:
review:
- type: approval
This indicates that changes originating from the GitHub connection named my-github must have an approved code review in order to be enqueued into the pipeline.
The dictionary passed to the GitHub pipeline require attribute supports the following attributes:
This requires that a certain kind of code review be present for the pull request (it could be added by the event in question). It takes several sub-parameters, all of which are optional and are combined together so that there must be a code review matching all specified requirements.
If present, a code review from this username is required. It is treated as a regular expression.
If present, a code review with this email address is required. It is treated as a regular expression.
If present, the code review must be older than this amount of time to match. Provide a time interval as a number with a suffix of "w" (weeks), "d" (days), "h" (hours), "m" (minutes), "s" (seconds). Example
48h
or2d
.If present, the code review must be newer than this amount of time to match. Same format as "older-than".
If present, the code review must match this type (or types).
If present, the author of the code review must have this permission (or permissions). The available values are
read
,write
, andadmin
.A boolean value (
true
orfalse
) that indicates whether the change must be open or closed in order to be enqueued.A boolean value (
true
orfalse
) that indicates whether the item must be associated with the latest commit in the pull request in order to be enqueued.A string value that corresponds with the status of the pull request. The syntax is
user:status:value
.A string value indicating that the pull request must have the indicated label (or labels).
The reject attribute is the mirror of the require attribute. It also accepts a dictionary under the connection name. This dictionary supports the following attributes:
This takes a list of code reviews. If a code review matches the provided criteria the pull request can not be entered into the pipeline. It follows the same syntax as the
review pipeline requirement above <github-pipeline-require-review>
.