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:
Repository administration: Read
Checks: Read & Write
Repository contents: Read & Write (write to let zuul merge change)
Issues: Read & Write
Pull requests: Read & Write
Commit statuses: Read & Write
Set events subscription:
Check run
Commit comment
Create
Push
Release
Issue comment
Issues
Label
Pull request
Pull request review
Pull request review comment
Status
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
Note
GitHub Pull Requests that modify GitHub Actions workflow configuration files cannot be merged by application credentials (this is any Pull Request that edits the .github/workflows directory and its contents). These Pull Requests must be merged by a normal user account. This means that Zuul will be limited to posting test results and cannot merge these PRs automatically when they pass testing.
GitHub Actions are still in Beta and this behavior may change.
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>
-
<github connection>.driver (required)
- github
The connection must set
driver=github
for GitHub connections.
-
<github connection>.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.
-
<github connection>.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.
-
<github connection>.api_token
API token for accessing GitHub if Zuul is configured with Webhooks. See Creating an access token for command-line use.
-
<github connection>.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.
-
<github connection>.sshkey
Default:~/.ssh/id_rsa
Path to SSH key to use when cloning github repositories if Zuul is configured with Webhooks.
-
<github connection>.server
Default:github.com
Hostname of the github install (such as a GitHub Enterprise).
-
<github connection>.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.
-
<github connection>.verify_ssl
Default:true
Enable or disable ssl verification for GitHub Enterprise. This is useful for a connection to a test installation.
-
<github connection>.rate_limit_logging
Default:true
Enable or disable GitHub rate limit logging. If rate limiting is disabled in GitHub Enterprise this can save some network round trip times.
-
<github connection>.driver (required)
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:-
pipeline.trigger.<github source>.event (required)
The event from github. Supported events are:
- pull_request
- pull_request_review
- push
- check_run
-
pipeline.trigger.<github source>.action
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 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 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.
A check_run event will have associated action(s) to trigger from. The supported actions are:
- requested
A check run is requested.
- completed
A check run completed.
-
pipeline.trigger.<github source>.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.
-
pipeline.trigger.<github source>.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.
-
pipeline.trigger.<github source>.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.
-
pipeline.trigger.<github source>.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
.
-
pipeline.trigger.<github source>.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
.
-
pipeline.trigger.<github source>.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.
-
pipeline.trigger.<github source>.event (required)
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 attributes support the following attributes:
-
pipeline.<reporter>.<github source>.status
Default:None
Type: str Report status via the Github status API. Set to one of
pending
success
failure
This is usually mutually exclusive with a value set in pipeline.<reporter>.<github source>.check, since this reports similar results via a different API. This API is older and results do not show up on the “checks” tab in the Github UI. It is recommended to use check unless you have a specific reason to use the status API.
-
pipeline.<reporter>.<github source>.status-url
Default:link to the build status page
Type: string URL to set in the Github status.
Defaults to a link to the build status or results page. This should probably be left blank unless there is a specific reason to override it.
-
pipeline.<reporter>.<github source>.check
Type: string Report status via the Github checks API. Set to one of
cancelled
failure
in_progress
neutral
skipped
success
This is usually mutually exclusive with a value set in pipeline.<reporter>.<github source>.status, since this reports similar results via a different API.
-
pipeline.<reporter>.<github source>.comment
Default:true
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.
-
pipeline.<reporter>.<github source>.review
One of approve, comment, or request-changes that causes the reporter to submit a review with the specified status on Pull Request based items. Has no effect on other items.
-
pipeline.<reporter>.<github source>.review-body
Text that will be submitted as the body of the review. Required if review is set to comment or request-changes.
-
pipeline.<reporter>.<github source>.merge
Default:false
Boolean value that determines if the reporter should merge the pull reqeust. Only used for Pull Request based items.
-
pipeline.<reporter>.<github source>.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.
-
pipeline.<reporter>.<github source>.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.
-
pipeline.<reporter>.<github source>.status
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 configuration such
as the following:
pipeline:
require:
my-github:
review:
- type: approved
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:
-
pipeline.require.<github source>.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.
-
pipeline.require.<github source>.review.username
If present, a code review from this username is required. It is treated as a regular expression.
-
pipeline.require.<github source>.review.email
If present, a code review with this email address is required. It is treated as a regular expression.
-
pipeline.require.<github source>.review.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
or2d
.
-
pipeline.require.<github source>.review.newer-than
If present, the code review must be newer than this amount of time to match. Same format as “older-than”.
-
pipeline.require.<github source>.review.type
If present, the code review must match this type (or types).
-
pipeline.require.<github source>.review.permission
If present, the author of the code review must have this permission (or permissions). The available values are
read
,write
, andadmin
.
-
pipeline.require.<github source>.review.username
-
pipeline.require.<github source>.open
A boolean value (
true
orfalse
) that indicates whether the change must be open or closed in order to be enqueued.
-
pipeline.require.<github source>.merged
A boolean value (
true
orfalse
) that indicates whether the change must be merged or not in order to be enqueued.
-
pipeline.require.<github source>.current-patchset
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.
-
pipeline.require.<github source>.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.Zuul does not differentiate between a status reported via status API or via checks API (which is also how Github behaves in terms of branch protection and status checks). Thus, the status could be reported by a pipeline.<reporter>.<github source>.status or a pipeline.<reporter>.<github source>.check.
When a status is reported via the status API, Github will add a
[bot]
to the name of the app that reported the status, resulting in something likeuser[bot]:status:value
. For a status reported via the checks API, the app’s slug will be used as is.
-
pipeline.require.<github source>.label
A string value indicating that the pull request must have the indicated label (or labels).
-
pipeline.require.<github source>.review
-
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:
-
pipeline.reject.<github source>.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
-
pipeline.reject.<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:
- pipeline:
name: check
description: |
Newly uploaded patchsets enter this pipeline to receive an
initial check status.
manager: independent
trigger:
github:
# Run this pipeline on new/changed pull requests
- event: pull_request
action:
- opened
- changed
- reopened
# Run in response to a pull request comment "recheck"
- event: pull_request
action: comment
comment: (?i)^\s*recheck\s*$
# When using the checks API to report results, failed runs
# will have a "re-run" button which emits this event.
- event: check_run
action: rerequested
check: .*/check:.*
start:
github:
check: 'in_progress'
comment: false
# It is recommended to use the checks API for consistency with
# other common CI tools that integrate with Github. Results
# will appear on the "checks" tab of PR and changes. There is
# generally no need to have Zuul leave comments when using the
# checks API.
#
# The older status API appears inline with the PR and can be
# enabled by uncommenting the "status:" in the various
# sections below. You should choose one or the other
# depending on project preferences.
#
#status: 'pending'
#comment: false
success:
github:
check: 'success'
comment: false
#status: 'success'
failure:
github:
check: 'failure'
comment: false
#status: 'failure'
dequeue:
github:
check: cancelled
comment: false
- 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:
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:
- event: pull_request_review
action: submitted
state: approved
- event: pull_request
action: comment
comment: (?i)^\s*regate\s*$
- event: pull_request_review
action: dismissed
state: request_changes
- event: pull_request
action: status
status: ".*:success"
- event: check_run
action: rerequested
check: .*/gate:.*
- event: pull_request
action: labeled
label:
- gate
start:
github:
check: 'in_progress'
comment: false
#status: 'pending'
success:
github:
check: 'success'
comment: false
#status: 'success'
merge: true
failure:
github:
check: 'failure'
#status: 'failure'
comment: false
dequeue:
github:
check: cancelled
comment: false
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:
- event: push
ref: ^refs/heads/.*$
- pipeline:
name: tag
description: This pipeline runs jobs in response to any tag event.
manager: independent
precedence: high
post-review: True
trigger:
github:
- event: push
ref: ^refs/tags/.*$