14 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
There are two options currently available. GitHub's project owner can either manually setup web-hook or install a GitHub Application. In the first case, the project's owner needs to know the zuul endpoint and the webhook secrets.
Web-Hook
To configure a project's webhook events:
- Set Payload URL to
http://<zuul-hostname>:<port>/api/connection/<connection-name>/payload
. - Set Content Type to
application/json
.
Select Events you are interested in. See below for the supported events.
You will also need to have a GitHub user created for your zuul:
- Zuul public key needs to be added to the GitHub account
- A api_token needs to be created too, see this article
Then in the zuul.conf, set webhook_token and api_token.
Application
To create a GitHub application:
- Go to your organization settings page to create the application, e.g.: https://github.com/organizations/my-org/settings/apps/new
- Set GitHub App name to "my-org-zuul"
- Set Setup URL to your setup documentation, when user install the application they are redirected to this url
- Set Webhook URL to
http://<zuul-hostname>:<port>/api/connection/<connection-name>/payload
. - Create a Webhook secret
- Set permissions:
- Commit statuses: Read & Write
- Issues: Read & Write
- Pull requests: Read & Write
- Repository contents: Read & Write (write to let zuul merge change)
- Repository administration: Read
- Set events subscription:
- Label
- Status
- Issue comment
- Issues
- Pull request
- Pull request review
- Pull request review comment
- Commit comment
- Create
- Push
- Release
- Set Where can this GitHub App be installed to "Any account"
- Create the App
- Generate a Private key in the app settings page
Then in the zuul.conf, set webhook_token, app_id and app_key. After restarting zuul-scheduler, verify in the 'Advanced' tab that the Ping payload works (green tick and 200 response)
Users can now install the application using its public page, e.g.: https://github.com/apps/my-org-zuul
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:
<github connection>
driver
github
The connection must set driver=github
for GitHub
connections.
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_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.
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.
server
Hostname of the github install (such as a GitHub Enterprise).
canonical_hostname
The canonical hostname associated with the git repos on the GitHub
server. Defaults to the value of <github
connection>.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.
verify_ssl
Enable or disable ssl verification for GitHub Enterprise. This is useful for a connection to a test installation.
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.
pipeline.trigger.<github source>
The dictionary passed to the GitHub pipeline trigger
attribute supports the following attributes:
event
The event from github. Supported events are:
pull_request
pull_request_review
push
action
A pipeline.trigger.<github source>.event.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 to pull request.
labeled
Label added to pull request.
unlabeled
Label removed from pull request.
status
Status set on commit. The syntax is user:status:value
.
This also can be a regular expression.
A pipeline.trigger.<github
source>.event.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 for pull_request
and
pull_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
and unlabeled
pull_request
actions. It accepts a list of strings each of
which matches the label name in the event literally.
label: recheck
will match a labeled
action
when pull request is labeled with a recheck
label.
label: 'do not test'
will match a unlabeled
action when a label with name do 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 of approved
, comment
, or
request_changes
.
status
This is used for pull-request
and status
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 of user: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 regular expression.
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.
pipeline.<reporter>.<github source>
To report to GitHub, the dictionaries passed to any of the pipeline
reporter<reporters>
attributes support the
following attributes:
status
String value (pending
, success
,
failure
) that the reporter should set as the commit status
on github.
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 that determines if the reporter should add a comment to the pipeline status to the github pull request. Only used for Pull Request based items.
merge
Boolean value that determines if the reporter should merge the pull reqeust. Only used for Pull Request based items.
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 items.
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 items.
Requirements Configuration
As described in pipeline.require
and 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.
pipeline.require.<github source>
The dictionary passed to the GitHub pipeline require attribute supports the following attributes:
review
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.
username
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.
older-than
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
or 2d
.
newer-than
If present, the code review must be newer than this amount of time to match. Same format as "older-than".
type
If present, the code review must match this type (or types).
permission
If present, the author of the code review must have this permission
(or permissions). The available values are read
,
write
, and admin
.
open
A boolean value (true
or false
) that
indicates whether the change must be open or closed in order to be
enqueued.
merged
A boolean value (true
or false
) that
indicates whether the change must be merged or not in order to be
enqueued.
current-patchset
A boolean value (true
or false
) that
indicates whether the item must be associated with the latest commit in
the pull request in order to be enqueued.
status
A string value that corresponds with the status of the pull request.
The syntax is user:status:value
. This can also be a regular
expression.
label
A string value indicating that the pull request must have the indicated label (or labels).
pipeline.reject.<github source>
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:
review
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 pipeline.require.<github source>.review