Zuul Config Resolver

Diagnostic tool for static Zuul variable resolution. Takes a job name, walks the parent inheritance chain across multiple repos, collects variables from job.vars, job.extra-vars, and include-vars files, deep-merges them (honoring !override/!inherit YAML tags), and outputs resolved variables with full provenance tracking. It also detects variable conflicts that Zuul resolves silently.

Installation

Install as a standalone CLI tool with uv:

uv tool install git+https://github.com/srac0/zuul-config-resolver

Or install from a local clone:

git clone https://github.com/srac0/zuul-config-resolver.git
cd zuul-config-resolver
uv tool install .

After installation, config-resolver is available on your PATH.

For development:

git clone https://github.com/srac0/zuul-config-resolver.git
cd zuul-config-resolver
uv sync
pre-commit install

Usage

Resolve a job

Clone the Zuul job repos side by side, then point config-resolver at them. When run from inside a Zuul repo, it uses the current directory by default.

config-resolver my-deploy-job

For multi-repo resolution, pass --repo-dir flags or use a config file:

config-resolver \
  --repo-dir ../zuul-jobs \
  --repo-dir ../project-config \
  my-deploy-job

Or with a config file:

# repos.yaml
repos:
  - ../zuul-jobs
  - ../project-config

config-resolver --config repos.yaml my-deploy-job

This writes two files to the current directory (override with --output-dir):

• resolved-vars.yaml - all merged variables, ready for ansible-playbook -e @resolved-vars.yaml
• resolved-vars-sources.yaml - maps each variable to its source file, job name, and merge history

Show conflicts

Find variables where a child job silently overrides a parent's value:

config-resolver --config repos.yaml --show-conflicts my-deploy-job

log_level (1 override):
  [debug] (my-deploy-job) <- [info] (base-deploy-job)
retry_count (1 override):
  [5] (my-deploy-job) <- [3] (base-deploy-job)

Show overrides

List all variables that are set at more than one level in the chain, even when the value stays the same:

config-resolver --config repos.yaml --show-overrides my-deploy-job

Inspect the parent chain

See each parent job with its source file and variable counts:

config-resolver --config repos.yaml --show-parents my-deploy-job

Diff against a branch

Compare resolved variables between the current working tree and a branch or commit:

config-resolver --repo-dir ../my-zuul-repo --diff origin/main

Without --repo-dir, the current directory is used:

cd my-zuul-repo
config-resolver --diff main

This prints a summary of added, removed, and changed jobs with their variable differences, and writes the full diff to resolved-vars-diff.yaml.

List all jobs

config-resolver --config repos.yaml --list-jobs

Help

config-resolver --help

Development

Without installing, use uv run to run the tool from a local checkout:

uv run config-resolver --list-jobs

Tests

uv run pytest

Lint and format

pre-commit run --all-files