zuul/doc/source/reference/drivers/mqtt.rst

title

MQTT Driver

MQTT

The MQTT driver supports reporters only. It is used to send MQTT message when items report.

Message Schema

An MQTT report uses this schema:

<mqtt schema>

action

The reporter action name, e.g.: 'start', 'success', 'failure', 'merge-failure', ...

tenant

The tenant name.

pipeline

The pipeline name.

project

The project name.

branch

The branch name.

change_url

The change url.

message

The report message.

change

The change number.

patchset

The patchset number.

commit_id

The commit id number.

owner

The owner username of the change.

ref

The change reference.

zuul_ref

The internal zuul change reference.

trigger_time

The timestamp when the event was added to the scheduler.

enqueue_time

The timestamp when the event was added to the pipeline.

buildset

The buildset information.

uuid

The buildset global uuid.

result

The buildset result

builds

The list of builds.

job_name

The job name.

voting

The job voting status.

uuid

The build uuid (not present in start report).

execute_time

The build execute time.

start_time

The build start time (not present in start report).

end_time

The build end time (not present in start report).

log_url

The build log url (not present in start report).

web_url

The url to the build result page. Not present in start report.

result

The build results (not present in start report).

artifacts

The build artifacts (not present in start report).

This is a list of dictionaries corresponding to the returned artifacts.

name

The name of the artifact.

url

The url of the artifact.

metadata

The metadata of the artifact. This is a dictionary of arbitrary key values determined by the job.

Here is an example of a start message:

{
  'action': 'start',
  'tenant': 'openstack.org',
  'pipeline': 'check',
  'project': 'sf-jobs',
  'branch': 'master',
  'change_url': 'https://gerrit.example.com/r/3',
  'message': 'Starting check jobs.',
  'trigger_time': '1524801056.2545864',
  'enqueue_time': '1524801093.5689457',
  'change': '3',
  'patchset': '1',
  'commit_id': '2db20c7fb26adf9ac9936a9e750ced9b4854a964',
  'owner': 'username',
  'ref': 'refs/changes/03/3/1',
  'zuul_ref': 'Zf8b3d7cd34f54cb396b488226589db8f',
  'buildset': {
    'uuid': 'f8b3d7cd34f54cb396b488226589db8f',
    'builds': [{
      'job_name': 'linters',
      'voting': True
    }],
  },
}

Here is an example of a success message:

{
  'action': 'success',
  'tenant': 'openstack.org',
  'pipeline': 'check',
  'project': 'sf-jobs',
  'branch': 'master',
  'change_url': 'https://gerrit.example.com/r/3',
  'message': 'Build succeeded.',
  'trigger_time': '1524801056.2545864',
  'enqueue_time': '1524801093.5689457',
  'change': '3',
  'patchset': '1',
  'commit_id': '2db20c7fb26adf9ac9936a9e750ced9b4854a964',
  'owner': 'username',
  'ref': 'refs/changes/03/3/1',
  'zuul_ref': 'Zf8b3d7cd34f54cb396b488226589db8f',
  'buildset': {
    'uuid': 'f8b3d7cd34f54cb396b488226589db8f',
    'builds': [{
      'job_name': 'linters',
      'voting': True
      'uuid': '16e3e55aca984c6c9a50cc3c5b21bb83',
      'execute_time': 1524801120.75632954,
      'start_time': 1524801179.8557224,
      'end_time': 1524801208.928095,
      'log_url': 'https://logs.example.com/logs/3/3/1/check/linters/16e3e55/',
      'web_url': 'https://tenant.example.com/t/tenant-one/build/16e3e55aca984c6c9a50cc3c5b21bb83/',
      'result': 'SUCCESS',
      'dependencies': [],
      'artifacts': [],
    }],
  },
}

Connection Configuration

<mqtt connection>

driver

mqtt

The connection must set driver=mqtt for MQTT connections.

server

MQTT server hostname or address to use.

port

MQTT server port.

keepalive

Maximum period in seconds allowed between communications with the broker.

user

Set a username for optional broker authentication.

password

Set a password for optional broker authentication.

ca_certs

A string path to the Certificate Authority certificate files to enable TLS connection.

certfile

A strings pointing to the PEM encoded client certificate to enable client TLS based authentication. This option requires keyfile to be set too.

keyfile

A strings pointing to the PEM encoded client private keys to enable client TLS based authentication. This option requires certfile to be set too.

ciphers

A string specifying which encryption ciphers are allowable for this connection. More information in this openssl doc.

Reporter Configuration

A connection<connections> that uses the mqtt driver must be supplied to the reporter. Each pipeline must provide a topic name. For example:

- pipeline:
    name: check
    success:
      mqtt:
        topic: "{tenant}/zuul/{pipeline}/{project}/{branch}/{change}"
        qos: 2

pipeline.<reporter>.<mqtt>

To report via MQTT message, the dictionaries passed to any of the pipeline reporter<reporters> support the following attributes:

topic

The MQTT topic to publish messages. The topic can be a format string that can use the following parameters: tenant, pipeline, project, branch, change, patchset and ref. MQTT topic can have hierarchy separated by /, more details in this doc

qos

The quality of service level to use, it can be 0, 1 or 2. Read more in this guide