Skip to content

Zuul configuration

  1. File structure
  2. Defining a Zuul tenant
  3. Integrating a repository with a Zuul tenant

File structure

When the config-check and config-update jobs are run on git events occurring on the config repository, the following file structure is expected:

|_ zuul/
       |_ main.yaml

Note

if the file structure is missing or partial the jobs will skip the related configuration check and update.

The file zuul/main.yaml holds the tenants configuration that will be applied the deployment.

Definition

A git repository is called a project within the Zuul terminology.

Defining a Zuul tenant

A Zuul tenant is defined through the zuul/main.yaml file. A Zuul tenant holds an isolated Zuul configuration from others Zuul tenants.

The configuration provided into zuul/main.yaml will be appended to the base configuration.

What happens during a config-update job?

When a change to zuul/main.yaml is merged, the following script is run to update Zuul's tenant configuration on the scheduler:

controllers/static/zuul/generate-tenant-config.sh
#!/bin/sh

set -ex

export HOME=/var/lib/zuul

# Generate the default tenants configuration file
cat << EOF > ~/main.yaml
- tenant:
    max-job-timeout: 10800
    name: internal
    report-build-page: true
    admin-rules:
      - admin-internal
    exclude-unprotected-branches: true
    source:
      git-server:
        config-projects:
        - system-config
      opendev.org:
        untrusted-projects:
        - zuul/zuul-jobs
EOF

if [ "$CONFIG_REPO_SET" == "TRUE" ]; then
  # A config repository has been set

  # config-update usage context required a specific git ref
  REF=$1

  /usr/local/bin/fetch-config-repo.sh $REF

  # Ensure the config repo enabled into the tenants config
  cat << EOF >> ~/main.yaml
      ${CONFIG_REPO_CONNECTION_NAME}:
        config-projects:
        - ${CONFIG_REPO_NAME}:
            load-branch: ${CONFIG_REPO_BRANCH}
EOF

  # Append the config repo provided tenant file to the default one
  if [ -f ~/config/zuul/main.yaml ]; then
    cat ~/config/zuul/main.yaml >> ~/main.yaml
  fi

fi

echo "Generated tenants config:"
echo
cat ~/main.yaml

Here is an example of a minimal tenant defintion:

- tenant:
    name: my-new-tenant
    source:
      my-gerrit-connection:
        config-projects:
          - my-tenant-config-repo
        untrusted-projects: []
      opendev.org:
        untrusted-projects:
          - zuul/zuul-jobs

Danger

Please take care not to override the internal tenant definition.

A minimal Zuul tenant should be populated with at least one config/trusted project. This tenant's config project (my-tenant-config-repo in the example above) defines Zuul configuration such as the pipelines, the base job and related base Ansible playbooks.

While the tenant's config project could be setup manually, we also provide a cli command to scaffold its content.

Note

The zuul/zuul-jobs project should always be part of a new tenant. The SF boostrap-tenant command expects that this repository is part of the tenant.

Info

The opendev.org connection is preconfigured on any Software-Factory deployment.

Bootstrap a config-project

sf-operator allows you to create a scaffolding for a new tenant's config repository. It defines:

  • the check, gate and post pipelines
  • the base job and playbooks

Warning

The tool only supports the definition of pipelines compatible with a Gerrit and GitLab connections.

Get a local checkout of the tenant's config project/repository then run:

sf-operator SF bootstrap-tenant </path/to/repository> --connection [connection]

Modify and merge

The scaffolding is yours to modify to suit your needs. Once you are happy with your changes, commit them and push them to your code review system.

If all went well you should see the pipelines appear in the Zuul status page for the related tenant. Also check for any tenant configuration problems by clicking on the blue bell on the Zuul web UI. Fix problems by pushing new commits into the repository until the tenant configuration errors page is clear.

Next steps ?

The Zuul tenant is now ready to be used. Other repositories can be added to the tenant definition (see the tenants configuration documentation).

Integrating a repository with a Zuul tenant

To integrate a repository inside a Zuul tenant, first the tenant must have been created then the repository must be added into the list of config/trusted or untrusted repositories for a given zuul connection.

Zuul might be configured to run jobs on this new repository, then make sure that the Zuul bot account for the related connection is authorized to set approvals, reports comments, (optionaly merge) changes (Github PRs, Gitlab MRs, Gerrit Reviews).

See the related section by connection type: