Docs: reformat github driver docs
Change-Id: Icb74dc39714b6efac4fcc1f1d44772982a236b35
This commit is contained in:
James E. Blair
parent
d23f45d12e
commit
02157ad419
|
|
@ -89,7 +89,7 @@ be able to invoke the ``gerrit stream-events`` command over SSH.
|
|||
|
||||
.. attr:: pipeline.trigger.<gerrit source>
|
||||
|
||||
The dictionary passed to the Gerrit pipeline `trigger` attribute
|
||||
The dictionary passed to the Gerrit pipeline ``trigger`` attribute
|
||||
supports the following attributes:
|
||||
|
||||
.. attr:: event
|
||||
|
|
|
|||
|
|
@ -29,135 +29,189 @@ 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:
|
||||
The supported options in ``zuul.conf`` connections are:
|
||||
|
||||
**driver=github**
|
||||
.. attr:: <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".
|
||||
``app_id=1234``
|
||||
.. attr:: driver
|
||||
:required:
|
||||
|
||||
**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``
|
||||
.. value:: github
|
||||
|
||||
**api_token**
|
||||
API token for accessing GitHub if Zuul is configured with Webhooks.
|
||||
See `Creating an access token for command-line use
|
||||
<https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_.
|
||||
The connection must set ``driver=github`` for GitHub connections.
|
||||
|
||||
**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
|
||||
<https://developer.github.com/webhooks/securing/>`_.
|
||||
.. attr:: app_id
|
||||
|
||||
**sshkey**
|
||||
Path to SSH key to use when cloning github repositories.
|
||||
``sshkey=/home/zuul/.ssh/id_rsa``
|
||||
App ID if you are using a *GitHub App*. Can be found under the
|
||||
**Public Link** on the right hand side labeled **ID**.
|
||||
|
||||
**server**
|
||||
Optional: Hostname of the github install (such as a GitHub Enterprise)
|
||||
If not specified, defaults to ``github.com``
|
||||
``server=github.myenterprise.com``
|
||||
.. attr:: app_key
|
||||
|
||||
**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``
|
||||
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.
|
||||
|
||||
**verify_ssl**
|
||||
Optional: Enable or disable ssl verification for GitHub Enterprise. This is
|
||||
useful for a connection to a test installation. If not specified, defaults
|
||||
to ``true``.
|
||||
``verify_ssl=true``
|
||||
.. attr:: api_token
|
||||
|
||||
API token for accessing GitHub if Zuul is configured with
|
||||
Webhooks. See `Creating an access token for command-line use
|
||||
<https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_.
|
||||
|
||||
.. attr:: 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
|
||||
<https://developer.github.com/webhooks/securing/>`_.
|
||||
|
||||
.. attr:: sshkey
|
||||
:default: ~/.ssh/id_rsa
|
||||
|
||||
Path to SSH key to use when cloning github repositories.
|
||||
|
||||
.. attr:: server
|
||||
:default: github.com
|
||||
|
||||
Hostname of the github install (such as a GitHub Enterprise).
|
||||
|
||||
.. attr:: canonical_hostname
|
||||
|
||||
The canonical hostname associated with the git repos on the
|
||||
GitHub server. Defaults to the value of :attr:`<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.
|
||||
|
||||
.. attr:: verify_ssl
|
||||
:default: true
|
||||
|
||||
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.
|
||||
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``, and ``push``.
|
||||
.. attr:: pipeline.trigger.<github source>
|
||||
|
||||
A ``pull_request`` event will have associated action(s) to trigger
|
||||
from. The supported actions are:
|
||||
The dictionary passed to the GitHub pipeline ``trigger`` attribute
|
||||
supports the following attributes:
|
||||
|
||||
*opened* - pull request opened
|
||||
.. attr:: event
|
||||
:required:
|
||||
|
||||
*changed* - pull request synchronized
|
||||
The event from github. Supported events are:
|
||||
|
||||
*closed* - pull request closed
|
||||
.. value:: pull_request
|
||||
|
||||
*reopened* - pull request reopened
|
||||
.. value:: pull_request_review
|
||||
|
||||
*comment* - comment added on pull request
|
||||
.. value:: push
|
||||
|
||||
*labeled* - label added on pull request
|
||||
.. attr:: action
|
||||
|
||||
*unlabeled* - label removed from pull request
|
||||
A :value:`pipeline.trigger.<github source>.event.pull_request`
|
||||
event will have associated action(s) to trigger from. The
|
||||
supported actions are:
|
||||
|
||||
*status* - status set on commit
|
||||
.. value:: opened
|
||||
|
||||
A ``pull_request_review`` event will
|
||||
have associated action(s) to trigger from. The supported actions are:
|
||||
Pull request opened.
|
||||
|
||||
*submitted* - pull request review added
|
||||
.. value:: changed
|
||||
|
||||
*dismissed* - pull request review removed
|
||||
Pull request synchronized.
|
||||
|
||||
**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.
|
||||
.. value:: closed
|
||||
|
||||
**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.
|
||||
Pull request closed.
|
||||
|
||||
**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.
|
||||
.. value:: reopened
|
||||
|
||||
**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``.
|
||||
Pull request reopened.
|
||||
|
||||
**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``.
|
||||
.. value:: comment
|
||||
|
||||
**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.
|
||||
Comment added to pull request.
|
||||
|
||||
.. value:: labeled
|
||||
|
||||
Label added to pull request.
|
||||
|
||||
.. value:: unlabeled
|
||||
|
||||
Label removed from pull request.
|
||||
|
||||
.. value:: status
|
||||
|
||||
Status set on commit.
|
||||
|
||||
A :value:`pipeline.trigger.<github
|
||||
source>.event.pull_request_review` event will have associated
|
||||
action(s) to trigger from. The supported actions are:
|
||||
|
||||
.. value:: submitted
|
||||
|
||||
Pull request review added.
|
||||
|
||||
.. value:: dismissed
|
||||
|
||||
Pull request review removed.
|
||||
|
||||
.. attr:: 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.
|
||||
|
||||
.. attr:: 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.
|
||||
|
||||
.. attr:: 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.
|
||||
|
||||
.. attr:: 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``.
|
||||
|
||||
.. attr:: 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``.
|
||||
|
||||
.. attr:: 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
|
||||
----------------------
|
||||
|
|
@ -166,38 +220,51 @@ 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 :ref:`connection<connections>` that uses the github driver must be
|
||||
supplied to the reporter. It has the following options:
|
||||
.. attr:: pipeline.<reporter>.<github source>
|
||||
|
||||
**status**
|
||||
String value (``pending``, ``success``, ``failure``) that the
|
||||
reporter should set as the commit status on github. ``status:
|
||||
'success'``
|
||||
To report to GitHub, the dictionaries passed to any of the pipeline
|
||||
:ref:`reporter<reporters>` attributes support the following
|
||||
attributes:
|
||||
|
||||
**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.
|
||||
.. attr:: status
|
||||
|
||||
**comment**
|
||||
Boolean value (``true`` or ``false``) that determines if the
|
||||
reporter should add a comment to the pipeline status to the github
|
||||
pull request. Defaults to ``true``. Only used for Pull Request based
|
||||
events. ``comment: false``
|
||||
String value (``pending``, ``success``, ``failure``) that the
|
||||
reporter should set as the commit status on github.
|
||||
|
||||
**merge**
|
||||
Boolean value (``true`` or ``false``) that determines if the
|
||||
reporter should merge the pull reqeust. Defaults to ``false``. Only
|
||||
used for Pull Request based events. ``merge=true``
|
||||
.. TODO support role markup in :default: so we can xref
|
||||
:attr:`webapp.status_url` below
|
||||
|
||||
**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'``
|
||||
.. attr:: status-url
|
||||
:default: webapp.status_url or the empty string
|
||||
|
||||
**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'``
|
||||
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.
|
||||
|
||||
.. attr:: 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.
|
||||
|
||||
.. attr:: merge
|
||||
:default: false
|
||||
|
||||
Boolean value that determines if the reporter should merge the
|
||||
pull reqeust. Only used for Pull Request based items.
|
||||
|
||||
.. attr:: 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.
|
||||
|
||||
.. attr:: 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.
|
||||
|
||||
.. _Github App: https://developer.github.com/apps/
|
||||
|
||||
|
|
@ -208,7 +275,7 @@ As described in :attr:`pipeline.require` and :attr:`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
|
||||
from a GitHub source named ``my-github``, create a congfiguration such
|
||||
as the following::
|
||||
|
||||
pipeline:
|
||||
|
|
@ -218,7 +285,7 @@ as the following::
|
|||
- type: approval
|
||||
|
||||
This indicates that changes originating from the GitHub connection
|
||||
named *my-github* must have an approved code review in order to be
|
||||
named ``my-github`` must have an approved code review in order to be
|
||||
enqueued into the pipeline.
|
||||
|
||||
.. attr:: pipeline.require.<github source>
|
||||
|
|
@ -292,7 +359,6 @@ enqueued into the pipeline.
|
|||
A string value indicating that the pull request must have the
|
||||
indicated label (or labels).
|
||||
|
||||
|
||||
.. attr:: pipeline.reject.<github source>
|
||||
|
||||
The `reject` attribute is the mirror of the `require` attribute. It
|
||||
|
|
|
|||
Loading…
Reference in New Issue