Roles

add-authorized-keys

Install SSH public key(s) on all hosts

This role is intended to be run at the end of a failed job for which the build node set will be held with zuul’s autohold command.

It copies the public key(s) into the authorized_keys file of every host in the inventory, allowing privileged users to access the node set for debugging or post-mortem analysis.

Add this stanza at the end of your project’s base post playbook to activate this functionality:

- hosts: all
  roles:
    - role: add-authorized-keys
      public_keys:
        - public_key: ssh-rsa AAAAB... venkman@parapsy.columbia.edu
        - public_key: ssh-rsa AAAAB... spengler@parapsy.columbia.edu
      when: not zuul_success | bool

Caution

Including this role earlier in any playbook may allow the keys’ owners to tamper with the execution of the jobs. It is strongly advised against doing so.

Role Variables

ssh_public_keys

A list of keys to inject.

ssh_public_keys.public_key

A public key to inject into authorized_keys, or a URL to a public key.

add-build-sshkey

Generate and install a build-local SSH key on all hosts

This role is intended to be run on the Zuul Executor at the start of every job. It generates an SSH keypair and installs the public key in the authorized_keys file of every host in the inventory. It then removes the Zuul master key from this job’s SSH agent so that the original key used to log into all of the hosts is no longer accessible (any per-project keys, if present, remain available), then adds the newly generated private key.

Role Variables

zuul_temp_ssh_key

Where to put the newly-generated SSH private key.

add-fileserver

Add a remote fileserver to the inventory so that content can be uploaded in subsequent tasks or roles.

Role Variables

fileserver

Complex argument which contains the information about the remote destination as well as the authentication information needed. It is expected that this argument comes from a Secret.

fileserver.fqdn

The FQDN of the remote host.

fileserver.path

The remote path. Content will be put into a directory below this path that matches zuul.project.short_name. The full path including the project short name will be added to the hostvars of the host as zuul_fileserver_project_path.

fileserver.ssh_known_hosts

String containing known host signature for the remote host.

fileserver.ssh_private_key

Contents of the ssh private key to use.

fileserver.ssh_username
Default: ansible_user

Remote ssh user name to use.

fileserver_leading_path

This is an optional variable that will be inserted between the base of the path (provided by the path variable) and the zuul.project.short_name final path element.

add-gpgkey

Install a GPG private key onto a host.

Role Variables

gpg_key
Complex argument which contains the GPG private key. It is expected that this argument comes from a Secret.
gpg_key.private

The ascii-armored contents of the GPG private key.

add-launchpad-credentials

Add launchpadlib credentials and launchpadlib to a host

Role Variables

lp_creds
Complex argument which contains the information needed to log in to Launchpad. It is expected that this argument comes from a Secret.
lp_creds.access_token

Launchpad access token

lp_creds.access_secret

Launchpad access secret

lp_creds.consumer_key

Launchpad consumer key

add-sshkey

Add an ssh key to the host so that non-ansible ssh connections can be made.

Role Variables

ssh_key

Complex argument which contains the ssh key information. It is expected that this argument comes from a Secret.

ssh_key.ssh_known_hosts

String containing known host signature for the remote host.

ssh_key.ssh_private_key

Contents of the ssh private key to use.

ssh_key.fqdn

The FQDN of the remote host.

ansible-galaxy-import

Import ansible roles into ansible galaxy

Role Variables

ansible_galaxy_branch
Default: zuul.branch

The name of a branch to import.

ansible_galaxy_executable
Default: ansible-galaxy

Path to ansible-galaxy executable.

ansible_galaxy_info
Complex argument which contains the information about the Ansible Galaxy server as well as the authentication information needed. It is expected that this argument comes from a Secret.
ansible_galaxy_info.server
Default: https://galaxy.ansible.com

The API server destination.

ansible_galaxy_info.token

Identify with github token rather than username and password.

ara-report

If ARA is enabled, generates a report or saves a copy of the ARA database.

Role Variables

ara_report_run
Default: ``true``

Whether to run this role or not. Possible values:

  • true (always run)
  • false (never run)
  • failure (only run when there has been a failure)
ara_database_path
Default: ``{{ zuul.executor.work_root }}/.ara/ansible.sqlite``

Absolute path where the ARA database is expected on the control node. This should be where the ansible-playbook execution had ARA save the host, task and result data if you provided a custom location through ARA_DATABASE or an ansible.cfg file.

ara_report_type
Default: ``html``

Possible values:

  • html
  • database

html will have ARA generate and save a statically generated HTML report inside ara_report_path.

database will only save the raw ARA sqlite database inside ara_report_path. The database can then be downloaded by users or loaded dynamically by the ara-wsgi-sqlite middleware.

See the ARA documentation for details.

ara_compress_html
Default: ``true``

When report_type is ‘html’, whether to compress the ARA HTML output or not.

Tip

Make sure the web server is configured to set the required mimetypes in order to serve gzipped content properly.

ara_report_path
Default: ``ara``

This path is relative to the root of the log directory.

When report_type is ‘html’ directory where the HTML report will be generated. When report_type is ‘database’, directory where the database is saved.

bindep

Installs distro packages using bindep tool

Looks for a bindep.txt in a project’s source directory, or failing that a other-requirements.txt. If one exists, run bindep on the file to produce a list of required distro packages that do not exist and then install the missing packages.

Role Variables

bindep_dir
Default: {{ zuul.project.src_dir }}

The directory to look for bindep files in.

bindep_profile
Default: test

A specific bindep profile to request.

bindep_file

Path to a specific bindep file to read from.

bindep_command

Path to the bindep command. Defaults to unset which will look for a system installed bindep. If bindep_command is not found, bindep will be installed into a temporary virtualenv.

bindep_fallback

Path to a bindep fallback file to be used if no bindep file can be found in bindep.bindep_dir.

build-puppet-module

An ansible role to build a Puppet module. This role assumes that Puppet is already installed on the target system (either manually or using bindep).

Role Variables

puppet_module_chdir
Default: {{ zuul.project.src_dir }}

The folder to switch into in order to build the Puppet module

build-python-release

Build sdist and wheel for Python projects.

Role Variables

release_python
Default: python

The python interpreter to use. Set it to “python3” to use python 3, for example.

bdist_wheel_xargs
Default: ''

Extra arguments to pass to the bdist_wheel command when building packages.

build-releasenotes

Build releasenotes for a project, optionally incorporating translations.

Role Variables

zuul_work_virtualenv
Default: ~/.venv

Virtualenv location in which to install things.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to build releasenotes in.

buildset-artifacts-location

Return the location of buildset logs

When a ‘buildset’ directory exists in the job logs, then use zuul_return to set buildset_artifacts_url for children jobs.

rpm-build job:

  • Create a repository
  • Fetch the repository to “{{ zuul.executor.log_root }}/buildset”
  • Use the buildset-artifacts-location role

rpm-test jobs:

  • Install “{{ buildset_artficats_url }}” yum repository
  • Run integration tests
layout:
  jobs:
    - rpm-build
    - rpm-test1:
        dependencies:
          - rpm-build
    - rpm-test2:
        dependencies:
          - rpm-build

Role Variables

zuul_log_url

Base URL where logs are to be found.

zuul_log_path

Path of the logs. This optional when the role is used after ‘upload-logs’.

configure-mirrors

An ansible role to configure services to use mirrors.

Role Variables

mirror_fqdn
Default: {{ zuul_site_mirror_fqdn }}

The base host for mirror servers.

pypi_mirror

URL to override the generated pypi mirror url based on configure-mirrors.mirror_fqdn.

set_apt_mirrors_trusted
Default: False

Set to True in order to tag APT mirrors as trusted, needed when accessing unsigned mirrors with newer releases like Ubuntu Bionic.

copy-build-sshkey

Copy a build-local SSH key to a defined user on all hosts

This role is intended to be run on the Zuul Executor. It copies a generated build specific ssh key to a user and adds it to the authorized_keys file of every host in the inventory.

Role Variables

zuul_temp_ssh_key
Default: "{{ zuul.executor.work_root }}/{{ zuul.build }}_id_rsa"

Where to source the build private key

copy_sshkey_target_user
Default: root

The user to copy the sshkey to.

create-afs-token

Create kerberos / afs tokens

Role Variables

afs

Complex argument which contains the information about authentication information. It is expected this argument comes from a Secret.

afs.keytab

Base64 encoded contents of a keytab file. We’ll base64 decode before writing it to disk as a temporary file.

afs.service_name

The service name to use for kinit command.

destroy-afs-token

Destroy any active AFS / Kerberos tokens

emit-job-header

Log a few lines about the job.

Role Variables

zuul_log_url

Base URL where logs are to be found.

ensure-babel

Ensure babel is installed

Role Variables

constraints_file

Optional path to a pip constraints file for installing python libraries.

ensure-output-dirs

Ensure output directories are in place

Role Variables

zuul_output_dir
Default: {{ ansible_user_dir }}/zuul-output

Base directory for collecting job output.

ensure-python

Ensure specified python interpreter and development files are installed

Note

This role is only available for Debian based platforms currently.

Role Variables

python_version

Optional version of python interpreter to install, such as 3.7.

ensure-sphinx

Ensure sphinx is installed

Installs sphinx. Also installs any dependencies needed in the first of doc/requirements.txt and test-requirements.txt to be found.

All pip installs are done with a provided constraints file, if given.

Role Variables

constraints_file

Optional path to a pip constraints file for installing python libraries.

doc_building_packages
Default: ['sphinx']

List of python packages to install for building docs.

sphinx_python
Default: python2

Version of python to use, either python2 or python3.

zuul_work_virtualenv
Default: ~/.venv

Virtualenv location in which to install things.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to operate in.

ensure-tox

Ensure tox is installed

If tox is not already installed, it will be installed via pip in the user install directory (i.e., “pip install –user”).

ensure-twine

Ensure twine is installed.

Role Variables

twine_python
Default: python

The python interpreter to use to install twine if it is not already installed. Set it to “python3” to use python 3, for example.

fetch-coverage-output

Collect output from a coverage run

By default, this copies the output from a coverage run on the worker to the log root of the executor.

Role Variables

zuul_executor_dest
Default: {{ zuul.executor.log_root }}

The destination directory on the executor. By default, the log root.

coverage_output_src
Default: {{ zuul.project.src_dir }}/cover/

The location on the worker from which to fetch the coverage output detail. By default, the cover dir of the current project.

fetch-javascript-content-tarball

Fetch a Javascript content tarball back to be published.

A content tarball is one that contains built javascript/css artifacts, such as but not limited to those produced by the webpack ArchivePlugin.

Role Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to work in.

create_tarball_directory

Create a tarball with the contents of create_tarball_directory (relative to zuul_work_dir).

fetch-javascript-output

Collect outputs from a javascript build

Role Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to work in

javascript_content_dir
Default: dist

Directory, relative to zuul_work_dir, in which javascript output content is to be found.

Whether to copy the data pointed to by symlinks in the built content, or to copy them as symbolic links.

fetch-javascript-tarball

Fetch a Javascript tarball back to be published.

Role Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to run npm in.

fetch-puppet-module-output

Collect output from a puppet module build

fetch-python-sdist-output

Collect output from a python sdist build

fetch-sphinx-output

Collect output from a sphinx build

By default, this copies the output from the sphinx build on the worker to the log root of the executor.

Role Variables

zuul_executor_dest
Default: {{ zuul.executor.log_root }}

The destination directory on the executor. By default, the log root.

sphinx_build_dir
Default: doc/build

Directory relative to zuul_work_dir where build output will be put.

sphinx_output_suffix
Default: ''

Suffix to use for constructing the path. This is normally an empty string. If set to ‘/’ then, rsync will remove the last part from the original path.

sphinx_output_src
Default: {{ zuul_work_dir }}/{{ sphinx_build_dir }}/html{{ sphinx_output_suffix }}

The location on the worker from which to fetch the generated sphinx content. By default, the HTML doc build dir of the current project.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

The location of the main working directory of the job.

fetch-subunit-output

Collect subunit outputs

Role Variables

zuul_work_dir
Default: {{ ansible_user_dir }}/{{ zuul.project.src_dir }}

Directory to work in. It has to be a fully qualified path.

tox_envlist

tox environment that was used to run the tests originally.

fetch-tox-output

Collect log output from a tox build

Role Variables

tox_envlist
Default: venv

Which tox environment to fetch log output from.

tox_executable
Default: tox

Location of the tox executable.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory tox was run in.

fetch-translation-output

Collect output from a translation build

fetch-zuul-cloner

Fetch the zuul-cloner shim and install to the destination.

repo_src_dir

Location of the Zuul source repositories.

destination

Where to install the zuul-cloner shim. This should be the full path and filename.

find-constraints

Find a pip constraints file

Sets a variable upper_constraints which can be passed to a pip invocation.

Role Variables

constraints_file

Optional path to a pip constraints file for installing python libraries.

git-prepare-nodecache

Prepare an archive containing all repositories that are part of the job. This can be used to prepare the repos archive suitable for caching in the node image to be used by prepare-workspace-git.

The path to the resulting archive file will be stored in the git_cache_file variable. That variable can be used to push the archive to a place where it will be picked up to be baked into the node image.

Role variables

git_cache_root
Default: {{ansible_user_dir }}/git-cache"

Directory where the git cache should be prepared. Usually this should not be changed.

htmlify-logs

HTMLify text logs

This makes an HTML version of every file in the executor log directory with a .txt or .txt.gz extension. If the original was gzipped, the HTML version will be as well.

install-docker

An ansible role to install docker and configure it to use mirrors if available.

Role Variables

mirror_fqdn
Default: {{ zuul_site_mirror_fqdn }}

The base host for mirror servers.

docker_mirror

URL to override the generated docker hub mirror url based on install-docker.mirror_fqdn.

use_upstream_docker
Default: True

By default this role adds repositories to install docker from upstream docker. Set this to False to use the docker that comes with the distro.

docker_update_channel
Default: stable

Which update channel to use for upstream docker. The two choices are stable, which is the default and updates quarterly, and edge which updates monthly.

docker_version
Default: undefined

Declare this with the version of the docker package to install. Undefined will install the latest. This will look something like 18.06.1~ce~3-0~ubuntu. Only supported when using upstream docker repos.

install-if-python

Install the contents of a directory if they contain a python project.

Installs into a virtualenv.

Role Variables

install_package
Default: true

Flag indicating whether or not the software in the zuul_work_dir should be installed.

error_on_failure

Flag that indicates installation errors should result in failure. Failures in installing the target directory are ignored by default.

constraints_file

Optional path to a pip constraints file to use when installing.

zuul_work_virtualenv
Default: ~/.venv

Virtualenv location in which to install things.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to operate in.

install-javascript-packages

Install javascript dependencies needed for a project

Role Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

The directory to work in.

install-kubernetes

An ansible role to install kubernetes.

Role Variables

install_kubernetes_with_cluster
Default: True

If true, installs a Minikube cluster.

minikube_version
Default: latest

The version of Minikube to install.

install-nodejs

Install NodeJS from nodesource

Role Variables

node_version
Default: 6
install-yarn

Install yarn from yarnpkg repos

Role Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

The directory to work in.

yarn_lock_file_path
Default: {{ zuul_work_dir }}/yarn.lock

Path to yarn.lock file used by a project.

log-inventory

Log the inventory used to run the job to the job’s log dir.

This will result in the log collection roles logging the job inventory.

Role Variables

zuul_info_dir
Default: {{ zuul.executor.log_root }}/zuul-info

The directory path to store the inventory file.

mirror-workspace-git-repos

Mirror the local git repos to remote nodes

This role uses git operations (unlike prepare-workspace which uses rsync) to mirror the local prepared git repos to the remote nodes. This may be useful if the remote node already has a copy of some or all of the git repos.

multi-node-bridge

Configures a VXLAN virtual network overlay through an openvswitch network bridge between a ‘switch’ node and ‘peer’ nodes.

This allows members of the bridge to communicate with each other through the virtual network.

By default, this role will:

  • Install and start openvswitch
  • Set up a br-infra bridge on all nodes
  • Set up the connectivity between the switch and the peer with a virtual port
  • Set up an ip address on the bridge interface:
172.24.4.1/23 # switch node
172.41.4.2/23 # first peer
172.41.4.3/23 # second peer
...

Role requirements

This role requires and expects two groups to be set up in the Ansible host inventory in order to work:

  • switch (the node acting as the switch)
  • peers (nodes connected to the virtual switch ports)

Role variables

bridge_vni_offset
Default: 1000000

VXLAN Network Identifier offset (openvswitch key).

bridge_mtu
Default: Smallest mtu less 50 bytes for vxlan overhead

Bridge interface MTU. By default we determine this value by checking all interfaces on host, taking the smallest MTU and subtracting by 50 for vxlan overhead. Can be overridden explicitly if this does not work.

bridge_name
Default: br-infra

Name of the bridge interface.

bridge_configure_address
Default: true

Whether or not to configure an IP address on the bridge interface.

bridge_authorize_internal_traffic
Default: false

When bridge_configure_address is true, whether or not to set up firewall rules in order to allow traffic to flow freely within the bridge subnet (bridge_address_prefix.0/bridge_address_subnet).

bridge_address_prefix
Default: 172.24.4

The IP address range prefix.

bridge_address_offset
Default: 1

The IP address offset, used with bridge_address_prefix to provide the full IP address. The initial offset defines the IP address of the switch node in the virtual network.

bridge_address_subnet
Default: 23

The IP address range CIDR/subnet.

multi-node-firewall

Configures the inventory private and public addresses in a multi-node job in iptables in order to allow traffic to and from each node without restrictions.

multi-node-hosts-file

Configures the inventory hostnames in a multi-node job resolve to their respective private ipv4 addresses through the /etc/hosts file on each node.

multi-node-known-hosts

Configures the file /etc/ssh/ssh_known_hosts on each node in a multi-node job to contain all known host names.

nodejs-test-dependencies

Install test dependencies for Node

npm

Run npm command in a source directory. Assumes the appropriate version of npm has been installed.

Role Variables

npm_command

Command to run. If it’s a standard npm lifecycle command, it will be run as npm {{ npm_command }}. Otherwise it will be run as npm run {{ npm_command }}.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to run npm in.

persistent-firewall

Saves current iptables rules for both ipv4 and ipv6 and makes them persistent so that they are available if iptables or the instance is restarted.

This role can be re-used more than once in order to persist new rules.

prepare-workspace

Prepare remote workspaces

This role is intended to run before any other role in a Zuul job.

It starts the Zuul console streamer on every host in the inventory, and then copies the prepared source repos to the working directory on every host.

prepare-workspace-git

Mirror the local git repos to remote nodes

This role uses git operations (unlike prepare-workspace which uses rsync) to mirror the locally prepared git repos to the remote nodes while taking advantage of cached repos on the node if they exist. This role works generically regardless of the existence of a cached repo on the node.

The cached repos need to be placed using the canonical name under the cached_repos_root directory.

Role Variables

cached_repos_root
Default: /opt/git

The root of the cached repos.

publish-artifacts-to-fileserver

Publish contents of {{ zuul.executor.work_root }}/artifacts/ dir using rsync over ssh to a remote fileserver that has previously been added to the inventory by add-fileserver.

Role Variables

add-fileserver sets the following variable in the hostvars of the hosts it adds, but it is documented for reference.

zuul_fileserver_project_path

The remote path. Content will be put into a directory below this path that matches zuul.project.short_name. The full path including the project short name will be added to the hostvars of the host as zuul_fileserver_project_path.

release-afs-volume

Run vos release on an AFS volume

Assumes a valid token has already been acquired via aklog.

Role Variables

afs_volume

String containing the name of the volume to release.

remove-build-sshkey

Remove the per-build SSH key from all hosts

The complement to add-build-sshkey. It removes the build’s SSH key from the authorized_keys files of all remote hosts.

Role Variables

zuul_temp_ssh_key

Where the per-build SSH private key was stored.

remove-gpgkey

Remove an added GPG key from the host.

remove-launchpad-credentials

Remove launchpadlib credentials from a host

Role Variables

launchpadlib_credentials

Path to the file containing the credentials.

remove-sshkey

Remove an added ssh key from the host.

Role Variables

ssh_key

Complex argument which contains the ssh key information. It is expected that this argument comes from a Secret.

ssh_key.ssh_known_hosts

String containing known host signature for the remote host.

ssh_key.fqdn

The FQDN of the remote host.

revoke-sudo

Remove sudo access for the Zuul user.

If the file /etc/sudoers.d/zuul exists, then it will be removed. This is to facilitate systems which may use the same image for tests which require sudo and those which do not.

This role also asserts that sudo access has been removed and will fail if it has not.

set-zuul-log-path-fact

Sets a fact named zuul_log_path from zuul variables

sign-artifacts

Sign artifacts

Role Variables

gpg_key
Complex argument which contains the GPG private key for signing the artifacts. It is expected that this argument comes from a Secret.
gpg_key.private

The ascii-armored contents of the GPG private key.

gpg_artifact_path
Default: "{{ zuul.executor.work_root }}/artifacts/"

Path to a directory containing artifacts to sign.

sphinx

Run sphinx to generate documentation

Role Variables

sphinx_source_dir
Default: doc/source

Directory relative to zuul_work_dir that contains the Sphinx sources.

sphinx_build_dir
Default: doc/build

Directory relative to zuul_work_dir where build output will be put.

sphinx_builders
Default: ['html']

Which sphinx builders to run.

sphinx_warning_is_error

Whether to treat sphinx build warnings as errors. Defaults to the value of [build_sphinx] warning-is-error in setup.cfg if defined, False if the [build_sphinx] section is present but the warning-is-error option is undefined, or True if the entire section is undefined.

zuul_work_virtualenv
Default: ~/.venv

Virtualenv that sphinx is installed in.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to operate in.

stage-output

Stage job output on the remote node

Takes as input a dictionary of files/folders named ‘zuul_copy_output’. Copies contents into {{ zuul_output_dir }} on the remote node and is intended to be used before output fetching in a base job’s post-playbook.

Role Variables

zuul_copy_output
Default: None

Dictionary of files and folders to be staged.

The input is a dictionary so that it can accumulated via zuul variable merging. Keys of the dictionary will be things to copy. Valid values describe the type of output to copy:

  • logs
  • artifacts
  • docs
  • null # ansible null, not the string null

null overrides the will of a parent job to copy something instructing not to copy.

stage_dir
Default: {{ ansible_user_dir }}

The stage directory on the remote node.

extensions_to_txt
Default: null

A dict of file extensions to be replaced with .txt when staging. This can be useful to ensure that text files with an extension not registered in the web server may be viewed via browser when uploaded to a file server.

Note that this is only used for files listed directly in zuul_copy_output and it won’t be applied to files contained in folders listed in zuul_copy_output.

Example:

extensions_to_txt:
  conf: True
  log: True
  txt: False

zuul.conf --(staged as)--> zuul_conf.txt
stage_compress_logs
Default: True

When True, files staged as logs will be compressed individually.

start-zuul-console

Start Zuul console logger

It starts the Zuul console streamer on every host in the inventory.

test-mirror-workspace-git-repos

Mirror the local git repos to remote nodes

This role uses git operations (unlike prepare-workspace which uses rsync) to mirror the local prepared git repos to the remote nodes. This may be useful if the remote node already has a copy of some or all of the git repos.

test-setup

Perform project test setup tasks.

This role assumes that Zuul has checked out a change for a project at src/{{ zuul.project.canonical_name }} and looks for a file named tools/test-setup.sh. If that file exists and is executable, it will be run.

This allows projects to specify test-setup steps (such as creating or initializing a database) in a form that can be easily run by both an automated testing system and developers.

Role Variables

test_setup_environment

Environment variables to pass in to the test-setup script.

test_setup_args

String of optional command line options passed to the test-setup script.

tox

Runs tox for a project

Role Variables

tox_environment

Environment variables to pass in to the tox run.

tox_envlist
Default: venv

Which tox environment to run.

tox_executable
Default: tox

Location of the tox executable.

tox_extra_args
Default: -vv

String of extra command line options to pass to tox.

tox_constraints_file

Path to a pip constraints file. Will be provided to tox via UPPER_CONSTRAINTS_FILE environment variable if it exists.

tox_install_siblings
Default: true

Flag controlling whether to attempt to install python packages from any other source code repos zuul has checked out. Defaults to True.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to run tox in.

trigger-readthedocs

Trigger readthedocs build for a project

Role Variables

rtd_project_name
Default: ``{{ zuul.project.short_name }}``

The readthedocs project name

rtd_webhook_id

The readthedocs webhook API ID. This needs to be taken from the project’s “Integrations” dashboard page in RTD. The URL will look like readthedocs.org/api/v2/webhook/<project-name>/<id>/.

This may come from a secret, however it can not be triggered without authentication.

rtd_credentials
Complex argument which contains the RTD authentication credentials. This is expected to come from a secret.
rtd_credentials.integration_token

The webhook integration token. You’ll find this value on the project’s “Integrations” dashboard page in RTD. This can be used instead of username/password combo.

rtd_credentials.username

The readthedocs username. If set, this will be used to authenticate in preference to any token set via rtd_integration_token.

rtd_credentials.password

Password for username. Must be set if username is set.

upload-afs

Copy contents from {{ zuul.executor.work_root }}/artifacts/ to AFS

Role Variables

afs_source

Path to local source directory.

afs_target

Target path in AFS (should begin with ‘/afs/…’).

upload-logs

Upload logs to a static webserver

This uploads logs to a static webserver using SSH.

Role Variables

zuul_log_url

Base URL where logs are to be found.

zuul_logserver_root
Default: /srv/static/logs

The root path to the logs on the logserver.

zuul_log_verbose
Default: false

The synchronize task in this role outputs a lot of information. By default, no_log is set to avoid overwhelming a reader of the logs. Set this to true to disable that behavior if it becomes necessary to debug this role.

zuul_site_upload_logs
Default: true

Controls when logs are uploaded. true, the default, means always upload logs. false means never upload logs. ‘failure’ means to only upload logs when the job has failed.

Note

Intended to be set by admins via site-variables.

upload-logs-swift

Upload logs to a swift container

This uploads logs to an OpenStack Object Store (Swift) container.

Role Variables

zuul_site_upload_logs
Default: true

Controls when logs are uploaded. true, the default, means always upload logs. false means never upload logs. ‘failure’ means to only upload logs when the job has failed.

Note

Intended to be set by admins via site-variables.

zuul_log_cloud_config

Complex argument which contains the cloud configuration in os-cloud-config (clouds.yaml) format. It is expected that this argument comes from a Secret.

zuul_log_partition
Default: false

If set to true, then the first component of the log path will be removed from the object name and added to the container name, so that logs for different changes are distributed across a large number of containers.

zuul_log_container
Default: logs

This role will create containers which do not already exist. If partitioning is not enabled, this is the name of the container which will be used. If partitioning is enabled, then this will be used as the prefix for the container name which will be separated from the partition name by an underscore. For example, “logs_42” would be the container name for partition 42.

zuul_log_container_public
Default: true

If the container is created, should it be created with global read ACLs. If the container already exists, it will not be modified.

zuul_log_delete_after
Default: 15552000

Number of seconds to delete objects after upload. Default is 6 months (15552000 seconds) and if set to 0 X-Delete-After will not be set.

zuul_log_path
Default: Generated by the role `set-zuul-log-path-fact`

Prepend this path to the object names when uploading.

upload-npm

Upload javascript packages to npm

Role Variables

npm_credentials
Complex argument which contains the information about the npm server as well as the authentication information needed. It is expected that this argument comes from a Secret. This role expects to be run on the executor.
npm_credentials.username

Username to use to log in to npm.

npm_credentials.password

Password to use to log in to npm.

npm_credentials.email

Email associated with the npm account.

npm_credentials.author_name

npm author name.

npm_credentials.author_url

npm author url.

npm_credentials.author_email

npm author email.

npm_credentials.registry_url
Default: //registry.npmjs.org

URL of npm registry server.

upload-pypi

Upload python packages to PyPI

Role Variables

pypi_info
Complex argument which contains the information about the PyPI server as well as the authentication information needed. It is expected that this argument comes from a Secret.
pypi_info.username

Username to use to log in to PyPI.

pypi_info.password

Password to use to log in to PyPI.

pypi_info.repository
Default: pypi

Name of the repository to upload to.

pypi_info.repository_url
Default: The built-in twine default for the production pypi.org service.

URL of the PyPI repostory.

pypi_path
Default: src/{{ zuul.project.canonical_name }}/dist

Path containing artifacts to upload.

pypi_twine_executable
Default: twine

Path to twine executable.

validate-host

Log information about the build node

Role Variables

zuul_site_traceroute_host

If defined, a host to run a traceroute against to verify build node network connectivity.

zuul_site_image_manifest_files
Default: ['/etc/dib-builddate.txt', '/etc/image-hostname.txt']

A list of files to read from the filesystem of the build node and whose contents will be logged. The default files are files written to nodes by diskimage-builder.

version-from-git

Sets three facts based on information in a git repo.

scm_sha
The short sha found in the repository.
project_ver
A string describing the project’s version. It will either be the value of {{ zuul.tag }} or {{ scm_tag }}.{{ commits_since_tag }}.{{ scm_sha }} otherwise where scm_tag is either the most recent tag or the value of scm_sha if there are no commits in the repo.
commits_since_tag
Number of commits since the most recent tag.

Role Variables

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to run git in.

write-inventory

Write an abbreviated version of the Zuul inventory to a file

This writes the minimal information about hosts from the current Zuul inventory to a file. It may be used to subsequently invoke Ansible with the inventory for the job.

Role Variables

write_inventory_dest

The path of the inventory file to write.

write_inventory_include_hostvars

A list of facts about the host to include. By default this parameter is omitted and all variables about a host will be included. To only include certain variables, list them here. The empty list will cause no variables to be included.

write_inventory_exclude_hostvars

A list of facts about the host to exclude. By default, all variables about a host will be included. To exclude certain variables, list them here.

yarn

Run yarn command in a source directory. Assumes the appropriate version of yarn has been installed.

Role Variables

yarn_command

Command to run. If it’s a standard lifecycle command, it will be run as yarn {{ yarn_command }}. Otherwise it will be run as yarn run {{ yarn_command }}.

zuul_work_dir
Default: {{ zuul.project.src_dir }}

Directory to run yarn in.