Zuul

https://zuul-ci.org/docs/zuul/latest/
Admin
Zuul is a program that drives continuous integration, delivery, and deployment systems with a focus...
Tokens:199,929
Snippets:3,570
Trust Score:9.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### MQTT Start Message Example

Source: https://zuul-ci.org/docs/zuul/latest/_sources/drivers/mqtt.rst.txt

Example JSON payload sent when a build process starts.

```javascript
{
  '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
    }],
  },
}
```

--------------------------------

### Start Zuul and Gerrit Services

Source: https://zuul-ci.org/docs/zuul/latest/_sources/tutorials/quick-start.rst.txt

Navigate to the example directory and launch the services using Docker Compose.

```shell
cd zuul/doc/source/examples
docker compose -p zuul-tutorial up
```

--------------------------------

### Install Javascript Tools

Source: https://zuul-ci.org/docs/zuul/latest/_sources/developer/javascript.rst.txt

Executes the installation script to set up nodejs and yarn repositories and packages.

```console
tools/install-js-tools.sh
```

--------------------------------

### Install dependencies

Source: https://zuul-ci.org/docs/zuul/latest/developer/javascript.html

Installs all dependencies defined in the project configuration.

```bash
yarn install
```

--------------------------------

### Manual Enqueue Examples

Source: https://zuul-ci.org/docs/zuul/latest/client.html

Examples for re-triggering release tags, periodic jobs, and post-merge events.

```bash
zuul-admin enqueue-ref --tenant openstack --trigger gerrit --pipeline release --project openstack/example_project --ref refs/tags/X.Y.Z --newrev abc123..
```

```bash
zuul-admin enqueue-ref --tenant openstack --trigger timer --pipeline periodic --project openstack/example_project --ref refs/heads/master
```

```bash
NEW_REF=$(git rev-parse HEAD)
OLD_REF=$(git rev-parse HEAD~1)

zuul-admin enqueue-ref --tenant openstack --trigger gerrit --pipeline post --project openstack/example_project --ref refs/heads/master --newrev $NEW_REF --oldrev $OLD_REF
```

--------------------------------

### Start the development server

Source: https://zuul-ci.org/docs/zuul/latest/_sources/developer/javascript.rst.txt

Launch the development server with hot-reloading on localhost:3000.

```bash
yarn start
```

--------------------------------

### Install reno

Source: https://zuul-ci.org/docs/zuul/latest/_sources/developer/releasenotes.rst.txt

Install the reno tool locally using pip to manage release notes.

```bash
pip install --user reno
```

--------------------------------

### MQTT Success Message Example

Source: https://zuul-ci.org/docs/zuul/latest/_sources/drivers/mqtt.rst.txt

Example JSON payload sent when a build process completes successfully.

```javascript
{
  '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': [],
    }],
  },
}
```

--------------------------------

### Promote Request

Source: https://zuul-ci.org/docs/zuul/latest/rest-api.html

Example request to trigger a promotion within a tenant.

```http
GET /api/tenant/{tenant_name}/promote HTTP/1.1
Host: example.com

```

--------------------------------

### MQTT Report Message Examples

Source: https://zuul-ci.org/docs/zuul/latest/drivers/mqtt.html

Example JSON payloads for MQTT reports generated by Zuul, illustrating the structure for start and success actions.

```json
{
  '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
    }],
  },
}
```

```json
{
  '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': [],
    }],
  },
}
```

--------------------------------

### Get Status Request

Source: https://zuul-ci.org/docs/zuul/latest/rest-api.html

Example request to retrieve the status of a tenant.

```http
GET /api/tenant/{tenant_name}/status HTTP/1.1
Host: example.com

```

--------------------------------

### Get State Request

Source: https://zuul-ci.org/docs/zuul/latest/rest-api.html

Example request to retrieve the current state of a tenant.

```http
GET /api/tenant/{tenant_name}/state HTTP/1.1
Host: example.com

```

--------------------------------

### Build the project

Source: https://zuul-ci.org/docs/zuul/latest/_sources/developer/javascript.rst.txt

Compile the project and place output files into the static directory.

```bash
yarn build
```

--------------------------------

### Get Change Status Request

Source: https://zuul-ci.org/docs/zuul/latest/rest-api.html

Example request to retrieve the status for a specific change.

```http
GET /api/tenant/{tenant_name}/status/change/{change} HTTP/1.1
Host: example.com

```

--------------------------------

### Example zuul.conf Configuration

Source: https://zuul-ci.org/docs/zuul/latest/_sources/configuration.rst.txt

A sample configuration file demonstrating the INI syntax used for various Zuul components.

```ini
[zookeeper]
hosts=zk1.example.com,zk2.example.com,zk3.example.com

[database]
dburi=<URI>

[keystore]
password=MY_SECRET_PASSWORD

[web]
root=https://zuul.example.com/

[scheduler]
log_config=/etc/zuul/scheduler-logging.yaml
```

--------------------------------

### Clone project and prepare directory

Source: https://zuul-ci.org/docs/zuul/latest/_sources/tutorials/quick-start.rst.txt

Commands to clone the test project and create a directory for playbooks.

```shell
cd ..
git clone http://localhost:8080/test1
```

```shell
cd test1
mkdir playbooks
```

--------------------------------

### Start Zuul Executor

Source: https://zuul-ci.org/docs/zuul/latest/_sources/operation.rst.txt

Command to start the Zuul executor process.

```bash
zuul-executor
```

--------------------------------

### Start Zuul Scheduler

Source: https://zuul-ci.org/docs/zuul/latest/_sources/operation.rst.txt

Command to start the Zuul scheduler process.

```bash
zuul-scheduler
```

--------------------------------

### Define Authorization Rules and Roles in YAML

Source: https://zuul-ci.org/docs/zuul/latest/_sources/developer/specs/web-rbac.rst.txt

Example configuration demonstrating how to define authorization rules, custom roles with specific permissions, and tenant role mappings.

```yaml
- authorization-rule:
    name: admin-user
    conditions:
      - preferred_username: admin

- authorization-rule:
    name: alice
    conditions:
      - preferred_username: alice

- authorization-rule:
    name: everyone
    conditions:
      - iss: our-institution

- role:
    name: autohold
    permissions:
      autohold: true

- role:
    name: enqueue-post
    permissions:
      enqueue:
        conditions:
          pipeline: post
          project: foo

- tenant:
    name: example
    anonymous-read-access: false
    role-mappings:
      admin-user: admin
      everyone: [read, autohold]
      alice: enqueue-post
```

--------------------------------

### Install Required Packages

Source: https://zuul-ci.org/docs/zuul/latest/_sources/tutorials/quick-start.rst.txt

Install necessary dependencies for Zuul on various Linux distributions.

```shell
# Fedora:

sudo dnf install git git-review docker-compose

# OpenSuse:

sudo zypper install git git-review docker-compose

# Ubuntu (Noble or later) / Debian:

sudo apt update
sudo apt install git git-review docker-compose-v2
```

--------------------------------

### Shared Project Configuration Example

Source: https://zuul-ci.org/docs/zuul/latest/_sources/developer/specs/nodepool-in-zuul.rst.txt

Defines base images, flavors, labels, and sections for use across multiple tenants.

```yaml
# Images, flavors, and labels are the building blocks of the
   # configuration.

   - image:
       name: centos-7
       type: zuul
       # Any other image-related info such as:
       # username: ...
       # python-path: ...
       # shell-type: ...
       # A default that can be overridden by a provider:
       # config-drive: true

   - image:
       name: ubuntu
       type: cloud

   - flavor:
       name: large

   - label:
       name: centos-7
       min-ready: 1
       flavor: large
       image: centos-7

   - label:
       name: ubuntu
       flavor: small
       image: ubuntu

   # A section for each cloud+region+az

   - section:
       name: rax-base
       abstract: true
       connection: rackspace
       boot-timeout: 120
       launch-timeout: 600
       key-name: infra-root-keys-2020-05-13
       # The launcher will apply the minimum of the quota reported by the
       # driver (if available) or the values here.
       quota:
         instances: 2000
       subnet: some-subnet
       tags:
         section-info: foo
       # We attach both kinds of images to providers in order to provide
       # image-specific info (like config-drive) or username.
       images:
         - name: centos-7
           config-drive: true
           # This is a Zuul image
         - name: ubuntu
           # This is a cloud image, so the specific cloud image name is required
           image-name: ibm-ubuntu-20-04-3-minimal-amd64-1
           # Other information may be provided
           # username ...
           # python-path: ...
           # shell-type: ...
       flavors:
         - name: small
           cloud-flavor: "Performance 8G"
         - name: large
           cloud-flavor: "Performance 16G"

   - section:
       name: rax-dfw
       parent: rax-base
       region: 'DFW'
       availability-zones: ["a", "b"]

   # A provider to indicate what labels are available to a tenant from
   # a section.

   - provider:
       name: rax-dfw-main
       section: rax-dfw
       labels:
         - name: centos-7
         - name: ubuntu
           key-name: infra-root-keys-2020-05-13
           tags:
             provider-info: bar
```

--------------------------------

### Create the configuration directory

Source: https://zuul-ci.org/docs/zuul/latest/_sources/tutorials/quick-start.rst.txt

Sets up the zuul.d directory within the cloned repository to store configuration files.

```shell
cd zuul-config
mkdir zuul.d
```

--------------------------------

### GET /api/tenant/{tenant_name}/badge

Source: https://zuul-ci.org/docs/zuul/latest/rest-api.html

Get a badge describing the result of the latest buildset found.

```APIDOC
## GET /api/tenant/{tenant_name}/badge

### Description
Get a badge describing the result of the latest buildset found.

### Method
GET

### Endpoint
/api/tenant/{tenant_name}/badge

### Parameters
#### Path Parameters
- **tenant_name** (string) - Required - The tenant name

#### Query Parameters
- **project** (string) - Optional - A project name
- **pipeline** (string) - Optional - A pipeline name
- **branch** (string) - Optional - A branch name

### Response
#### Success Response (200)
- **badge** (string) - Badge describing the result of the latest buildset found.

#### Error Response (404)
- **error** (string) - No buildset found
```

--------------------------------

### Example zuul.d directory structure

Source: https://zuul-ci.org/docs/zuul/latest/project-config.html

Demonstrates using numeric prefixes to ensure correct load order for configuration files within a zuul.d directory.

```text
* zuul.d/pipelines.yaml
* zuul.d/projects.yaml
* zuul.d/01_jobs.yaml
* zuul.d/02_jobs-variants.yaml
```

--------------------------------

### Promote command usage

Source: https://zuul-ci.org/docs/zuul/latest/client.html

Displays the command-line arguments and options for the promote action.

```bash
usage: zuul-admin 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
```

--------------------------------

### List Projects Request

Source: https://zuul-ci.org/docs/zuul/latest/rest-api.html

Example request to retrieve a list of projects for a given tenant.

```http
GET /api/tenant/{tenant_name}/projects HTTP/1.1
Host: example.com

```

--------------------------------

### Start Keycloak service

Source: https://zuul-ci.org/docs/zuul/latest/_sources/tutorials/keycloak.rst.txt

Launch the Keycloak container using the provided docker-compose file.

```shell
cd zuul/doc/source/examples/keycloak
docker compose -p zuul-tutorial-keycloak up -d
```
Tokens:
Raw