Commands

Privileged commands

Some commands require a valid authentication token to be passed as the --auth-token argument. Administrators can generate such a token for users as needed.

Usage

The general options that apply to all subcommands are:

usage: zuul-client [-h] [-c CONFIG] [--version] [-v] [--auth-token AUTH_TOKEN]
                   [--zuul-url ZUUL_URL] [--use-config ZUUL_CONFIG]
                   [--insecure]
                   {autohold,autohold-delete,autohold-info,autohold-list,enqueue,enqueue-ref,dequeue,promote,encrypt,builds}
                   ...

Zuul User CLI

optional arguments:
  -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
  --zuul-url ZUUL_URL   Zuul base URL, needed if using the client without a
                        configuration file
  --use-config ZUUL_CONFIG
                        A predefined configuration in .zuul.conf
  --insecure            Do not verify SSL connection to Zuul (Defaults to
                        False)

commands:
  valid commands

  {autohold,autohold-delete,autohold-info,autohold-list,enqueue,enqueue-ref,dequeue,promote,encrypt,builds}
                        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

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]

optional arguments:
  -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

optional arguments:
  -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

optional arguments:
  -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]

optional arguments:
  -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]

optional arguments:
  -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

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]

optional arguments:
  -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]

optional arguments:
  -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

optional arguments:
  -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.

optional arguments:
  -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.

Promote

Note

This command is only available with a valid authentication token.

usage: zuul-client promote [-h] [--tenant TENANT] --pipeline PIPELINE
                           --changes CHANGES [CHANGES ...]

optional arguments:
  -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.