1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
:title: Zuul Client
Zuul Client
===========
Zuul includes a simple command line client that may be used to affect Zuul's
behavior while running. It must be run on a host that has access to the Gearman
server (e.g., locally on the Zuul host), or on a host with access to Zuul's web
server.
Configuration
-------------
The client uses the same zuul.conf file as the server, and will look
for it in the same locations if not specified on the command line.
If both sections are present, the ``gearman`` section takes precedence over the
``webclient`` section, meaning the client will execute commands using the Gearman
server over the REST API.
It is also possible to run the client without a configuration file, by using the
``--zuul-url`` option to specify the base URL of the Zuul web server.
.. note:: Not all commands are available through the REST API.
Usage
-----
The general options that apply to all subcommands are:
.. program-output:: zuul --help
The following subcommands are supported:
Autohold
^^^^^^^^
.. program-output:: zuul autohold --help
Example::
zuul autohold --tenant openstack --project example_project --job example_job --reason "reason text" --count 1
Autohold Delete
^^^^^^^^^^^^^^^
.. program-output:: zuul autohold-delete --help
Example::
zuul autohold-delete --id 0000000123
Autohold List
^^^^^^^^^^^^^
.. program-output:: zuul autohold-list --help
Example::
zuul autohold-list
Dequeue
^^^^^^^
.. program-output:: zuul dequeue --help
Examples::
zuul dequeue --tenant openstack --pipeline check --project example_project --change 5,1
zuul dequeue --tenant openstack --pipeline periodic --project example_project --ref refs/heads/master
Enqueue
^^^^^^^
.. program-output:: zuul enqueue --help
Example::
zuul enqueue --tenant openstack --trigger gerrit --pipeline check --project example_project --change 12345,1
Note that the format of change id is <number>,<patchset>.
Enqueue-ref
^^^^^^^^^^^
.. program-output:: zuul enqueue-ref --help
This command is provided to manually simulate a trigger from an
external source. It can be useful for testing or replaying a trigger
that is difficult or impossible to recreate at the source. The
arguments to ``enqueue-ref`` will vary depending on the source and
type of trigger. Some familiarity with the arguments emitted by
``gerrit`` `update hooks
<https://gerrit-review.googlesource.com/admin/projects/plugins/hooks>`__
such as ``patchset-created`` and ``ref-updated`` is recommended. Some
examples of common operations are provided below.
Manual enqueue examples
***********************
It is common to have a ``release`` pipeline that listens for new tags
coming from ``gerrit`` and performs a range of code packaging jobs.
If there is an unexpected issue in the release jobs, the same tag can
not be recreated in ``gerrit`` and the user must either tag a new
release or request a manual re-triggering of the jobs. To re-trigger
the jobs, pass the failed tag as the ``ref`` argument and set
``newrev`` to the change associated with the tag in the project
repository (i.e. what you see from ``git show X.Y.Z``)::
zuul enqueue-ref --tenant openstack --trigger gerrit --pipeline release --project openstack/example_project --ref refs/tags/X.Y.Z --newrev abc123...
The command can also be used asynchronosly trigger a job in a
``periodic`` pipeline that would usually be run at a specific time by
the ``timer`` driver. For example, the following command would
trigger the ``periodic`` jobs against the current ``master`` branch
top-of-tree for a project::
zuul enqueue-ref --tenant openstack --trigger timer --pipeline periodic --project openstack/example_project --ref refs/heads/master
Another common pipeline is a ``post`` queue listening for ``gerrit``
merge results. Triggering here is slightly more complicated as you
wish to recreate the full ``ref-updated`` event from ``gerrit``. For
a new commit on ``master``, the gerrit ``ref-updated`` trigger
expresses "reset ``refs/heads/master`` for the project from ``oldrev``
to ``newrev``" (``newrev`` being the committed change). Thus to
replay the event, you could ``git log`` in the project and take the
current ``HEAD`` and the prior change, then enqueue the event::
NEW_REF=$(git rev-parse HEAD)
OLD_REF=$(git rev-parse HEAD~1)
zuul enqueue-ref --tenant openstack --trigger gerrit --pipeline post --project openstack/example_project --ref refs/heads/master --newrev $NEW_REF --oldrev $OLD_REF
Note that zero values for ``oldrev`` and ``newrev`` can indicate
branch creation and deletion; the source code is the best reference
for these more advanced operations.
Promote
^^^^^^^
.. note:: This command is only available through a Gearman connection.
.. program-output:: zuul promote --help
Example::
zuul promote --tenant openstack --pipeline check --changes 12345,1 13336,3
Note that the format of changes id is <number>,<patchset>.
Show
^^^^
.. note:: This command is only available through a Gearman connection.
.. program-output:: zuul show --help
Example::
zuul show running-jobs
tenant-conf-check
^^^^^^^^^^^^^^^^^
.. note:: This command is only available through a Gearman connection.
.. program-output:: zuul tenant-conf-check --help
Example::
zuul tenant-conf-check
This command validates the tenant configuration schema. It exits '-1' in
case of errors detected.
create-auth-token
^^^^^^^^^^^^^^^^^
.. note:: This command is only available if an authenticator is configured in
``zuul.conf``. Furthermore the authenticator's configuration must
include a signing secret.
.. program-output:: zuul create-auth-token --help
Example::
zuul create-auth-token --auth-config zuul-operator --user alice --tenant tenantA --expires-in 1800
The return value is the value of the ``Authorization`` header the user must set
when querying a protected endpoint on Zuul's REST API.
Example::
bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbWFuYWdlc2Yuc2ZyZG90ZXN0aW5zdGFuY2Uub3JnIiwienV1bC50ZW5hbnRzIjp7ImxvY2FsIjoiKiJ9LCJleHAiOjE1Mzc0MTcxOTguMzc3NTQ0fQ.DLbKx1J84wV4Vm7sv3zw9Bw9-WuIka7WkPQxGDAHz7s
|
