Commands
Privileged commands
Some commands require the user to be authenticated (and authorized). Zuul-client supports two forms of authentication:
user/password - Zuul-client will exchange the credentials for an access token on behalf of the user. This requires the identity provider to enable OpenID Connect’s “password” grant type (also known as Direct Access Grant).
raw JWT - The access token can be passed directly to zuul-client as the
--auth-tokenargument. Administrators can generate such a token for users as needed; an authenticated user on Zuul’s Web UI can also fetch their currently valid token on the UI’s user page.
Usage
The general options that apply to all subcommands are:
usage: zuul-client [-h] [-c CONFIG] [--version] [-v] [--auth-token AUTH_TOKEN]
[--username USERNAME] [--password PASSWORD]
[--zuul-url ZUUL_URL] [--use-config ZUUL_CONFIG]
[--insecure] [--format {JSON,json,text,dot}]
{autohold,autohold-delete,autohold-info,autohold-list,enqueue,enqueue-ref,dequeue,promote,encrypt,builds,build-info,job-graph,freeze-job}
...
Zuul User CLI
options:
-h, --help show this help message and exit
-c CONFIG specify the config file
--version show zuul version
-v verbose output
--auth-token AUTH_TOKEN
Authentication Token, required by admin commands
--username USERNAME User name, can be used to fetch an authentication
token if the identity provider supports direct access
grants
--password PASSWORD Password matching the user name. If only --username is
provided, the user will be prompted for a password
--zuul-url ZUUL_URL Zuul base URL, needed if using the client without a
configuration file
--use-config ZUUL_CONFIG
A predefined configuration in the zuul-client
configuration file
--insecure Do not verify SSL connection to Zuul (Defaults to
False)
--format {JSON,json,text,dot}
The output format, when applicable
commands:
valid commands
{autohold,autohold-delete,autohold-info,autohold-list,enqueue,enqueue-ref,dequeue,promote,encrypt,builds,build-info,job-graph,freeze-job}
additional help
autohold hold nodes for failed job
autohold-delete delete autohold request
autohold-info retrieve autohold request detailed info
autohold-list list autohold requests
enqueue enqueue a change
enqueue-ref enqueue a ref
dequeue dequeue a buildset by its change or ref
promote promote one or more changes
encrypt Encrypt a secret to be used in a project's jobs
builds List builds matching search criteria
build-info Get info on a specific build
job-graph Freeze and display a job graph
freeze-job Freeze and display a job
The following subcommands are supported:
Autohold
Note
This command is only available with a valid authentication token.
usage: zuul-client autohold [-h] [--tenant TENANT] --project PROJECT --job JOB
[--change CHANGE] [--ref REF] --reason REASON
[--count COUNT]
[--node-hold-expiration NODE_HOLD_EXPIRATION]
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--project PROJECT project name
--job JOB job name
--change CHANGE specific change to hold nodes for
--ref REF git ref to hold nodes for
--reason REASON reason for the hold
--count COUNT number of job runs (default: 1)
--node-hold-expiration NODE_HOLD_EXPIRATION
how long in seconds should the node set be in HOLD
status (default: scheduler's default_hold_expiration
value)
Example:
zuul-client autohold --tenant openstack --project example_project --job example_job --reason "reason text" --count 1
Autohold Delete
Note
This command is only available with a valid authentication token.
usage: zuul-client autohold-delete [-h] [--tenant TENANT] REQUEST_ID
positional arguments:
REQUEST_ID the hold request ID
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
Example:
zuul-client autohold-delete --tenant openstack --id 0000000123
Autohold Info
usage: zuul-client autohold-info [-h] [--tenant TENANT] REQUEST_ID
positional arguments:
REQUEST_ID the hold request ID
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
Example:
zuul-client autohold-info --tenant openstack --id 0000000123
Autohold List
usage: zuul-client autohold-list [-h] [--tenant TENANT]
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
Example:
zuul-client autohold-list --tenant openstack
Builds
usage: zuul-client builds [-h] [--tenant TENANT] [--project PROJECT]
[--pipeline PIPELINE] [--change CHANGE]
[--branch BRANCH] [--patchset PATCHSET] [--ref REF]
[--newrev NEWREV] [--job JOB] [--voting]
[--non-voting] [--node NODE] [--result RESULT]
[--final] [--held] [--limit LIMIT] [--skip SKIP]
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--project PROJECT project name
--pipeline PIPELINE pipeline name
--change CHANGE change reference
--branch BRANCH branch name
--patchset PATCHSET patchset number
--ref REF ref name
--newrev NEWREV the applied revision
--job JOB job name
--voting show voting builds only
--non-voting show non-voting builds only
--node NODE node name
--result RESULT build result
--final show final builds only
--held show held builds only
--limit LIMIT maximum amount of results to return
--skip SKIP how many results to skip
Examples:
zuul-client --use-conf sfio builds --tenant mytenant --result NODE_FAILURE
zuul-client --use-conf opendev builds --tenant zuul --project zuul/zuul-client --limit 10
Build-info
usage: zuul-client build-info [-h] [--tenant TENANT] --uuid UUID
[--show-job-output] [--show-artifacts]
[--show-inventory]
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--uuid UUID build UUID
--show-job-output Only download the job's output to the console
--show-artifacts Display only artifacts information for the build
--show-inventory Display only ansible inventory information for the build
Examples:
zuul-client build-info --tenant mytenant --uuid aaaaa
zuul-client build-info --tenant mytenant --uuid aaaaa --show-job-output
Dequeue
Note
This command is only available with a valid authentication token.
usage: zuul-client dequeue [-h] [--tenant TENANT] --pipeline PIPELINE
--project PROJECT [--change CHANGE] [--ref REF]
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--pipeline PIPELINE pipeline name
--project PROJECT project name
--change CHANGE change id
--ref REF ref name
Examples:
zuul-client dequeue --tenant openstack --pipeline check --project example_project --change 5,1
zuul-client dequeue --tenant openstack --pipeline periodic --project example_project --ref refs/heads/master
Encrypt
usage: zuul-client encrypt [-h] [--public-key /path/to/pubkey]
[--tenant TENANT] [--project PROJECT] [--no-strip]
[--secret-name SECRET_NAME]
[--field-name FIELD_NAME] [--infile INFILE]
[--outfile OUTFILE]
options:
-h, --help show this help message and exit
--public-key /path/to/pubkey
path to project public key (bypass API call)
--tenant TENANT tenant name
--project PROJECT project name
--no-strip Do not strip whitespace from beginning or end of
input. Ignored when --infile is used.
--secret-name SECRET_NAME
How the secret should be named. If not supplied, a
placeholder will be used.
--field-name FIELD_NAME
How the name of the secret variable. If not supplied,
a placeholder will be used.
--infile INFILE A filename whose contents will be encrypted. If not
supplied, the value will be read from standard input.
If entering the secret manually, press Ctrl+d when
finished to process the secret.
--outfile OUTFILE A filename to which the encrypted value will be
written. If not supplied, the value will be written to
standard output.
Examples:
zuul-client encrypt --tenant openstack --project config --infile .pypirc --outfile encrypted.yaml --secret-name pypi_creds --field-name pypirc
cat .pypirc | zuul-client encrypt --tenant openstack --project config
Enqueue
Note
This command is only available with a valid authentication token.
usage: zuul-client enqueue [-h] [--tenant TENANT] --pipeline PIPELINE
--project PROJECT --change CHANGE
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--pipeline PIPELINE pipeline name
--project PROJECT project name
--change CHANGE change id
Example:
zuul-client 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
Note
This command is only available with a valid authentication token.
usage: zuul-client enqueue-ref [-h] [--tenant TENANT] --pipeline PIPELINE
--project PROJECT --ref REF [--oldrev OLDREV]
[--newrev NEWREV]
Submit a trigger event
Directly enqueue a trigger event. This is usually used
to manually "replay" a trigger received from an external
source such as gerrit.
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--pipeline PIPELINE pipeline name
--project PROJECT project name
--ref REF ref name
--oldrev OLDREV old revision
--newrev NEWREV new revision
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
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-client 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-client 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-client 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 of Zuul is the best reference
for these more advanced operations.
Freeze-job
Display information about a job as it would be run in a particular project’s pipeline. This causes Zuul to combine all of the matching jobs and variants that would be used to form the final version of a job that would be executed for a change or ref as enqueued into the specified pipeline. This includes job attributes, playbook paths, nodesets, variables, etc. Secret names may be included but the values are redacted.
The default text output shows an abbreviated summary of only the most pertinent information. The JSON output reports all available information.
usage: zuul-client freeze-job [-h] [--tenant TENANT] --pipeline PIPELINE
--project PROJECT --branch BRANCH --job JOB
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--pipeline PIPELINE pipeline name
--project PROJECT project name
--branch BRANCH branch name
--job JOB job name
Example:
zuul-client freeze-job --tenant mytenant --pipeline check --project org/project --branch master --job tox
Job-graph
Display the set of jobs that would be triggered in a project’s pipeline. This will show the complete set of jobs that Zuul will consider running if an item for the given project and branch were enqueued into the specified pipeline. Information about job dependencies (soft and hard) is also included. The actual set of jobs run for a given change or ref may be less than what is output by this command if some jobs have non-matching file matchers.
This command supports the dot output format. When used, the
output may be supplied to graphviz in order to render a graphical view
of the job graph.
usage: zuul-client job-graph [-h] [--tenant TENANT] --pipeline PIPELINE
--project PROJECT --branch BRANCH
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--pipeline PIPELINE pipeline name
--project PROJECT project name
--branch BRANCH branch name
Example:
zuul-client job-graph --tenant mytenant --pipeline check --project org/project --branch master
zuul-client --format dot job-graph --tenant mytenant --pipeline check --project org/project --branch master | xdot
Promote
Note
This command is only available with a valid authentication token.
usage: zuul-client promote [-h] [--tenant TENANT] --pipeline PIPELINE
--changes CHANGES [CHANGES ...]
options:
-h, --help show this help message and exit
--tenant TENANT tenant name
--pipeline PIPELINE pipeline name
--changes CHANGES [CHANGES ...]
change ids
This command will push the listed changes at the top of the chosen pipeline.
Example:
zuul-client promote --tenant openstack --pipeline check --changes 12345,1 13336,3
Note that the format of changes id is <number>,<patchset>.
The promote action is used to reorder the change queue in a pipeline, by putting the provided changes at the top of the queue; therefore this action makes the most sense when performed against a dependent pipeline.
The most common use case for the promote action is the need to merge an urgent fix when the gate pipeline has already several patches queued ahead. This is especially needed if there is concern that one or more changes ahead in the queue may fail, thus increasing the time to land for the fix; or concern that the fix may not pass validation if applied on top of the current patch queue in the gate.
If the queue of a dependent pipeline is targeted by the promote, all the ongoing jobs in that queue will be canceled and restarted on top of the promoted changes.