generic-gitlab-cicd 0.3.2__py3-none-any.whl

generic_ci/__init__.py

@@ -0,0 +1,3 @@
+"""Public configuration compiler. Runtime images must carry this exact version."""
+
+__version__ = "0.3.2"

generic_ci/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

generic_ci/cli.py

@@ -0,0 +1,110 @@
+"""Offline authoring CLI: schema, validate, explain, render and drift checking."""
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from pydantic import ValidationError
+
+from .compiler import compile_pipeline, render, source_hashes
+from .config import load
+from .models import Pipeline, Platform
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == 'source':
+        from .sources import source_main
+        try:
+            return source_main(argv[1:])
+        except (ValueError, OSError, ValidationError) as error:
+            print(f'generic-ci: {error}', file=sys.stderr)
+            return 1
+    parser = argparse.ArgumentParser(prog="generic-ci")
+    parser.add_argument("command", choices=["schema", "validate", "explain", "render", "init"])
+    parser.add_argument("--config")
+    parser.add_argument("--format", choices=["workflows", "legacy"], default="workflows")
+    parser.add_argument("--ecosystem", choices=["python", "npm", "pnpm", "bun"], default="python")
+    parser.add_argument("--platform")
+    parser.add_argument("--template")
+    parser.add_argument("--source")
+    parser.add_argument("--repo")
+    parser.add_argument("--ref")
+    parser.add_argument("--offline", action="store_true")
+    parser.add_argument("--root", default=".")
+    parser.add_argument("--output", "-o")
+    parser.add_argument("--check", action="store_true", help="Fail if output differs; never modify output")
+    parser.add_argument("--platform-schema", action="store_true")
+    options = parser.parse_args(argv)
+    try:
+        root = Path(options.root).resolve()
+        use_source = options.format == 'workflows' and (root / 'generic-ci.yml').exists()
+        from .sources import home
+        default_source = (home() / 'sources.json').exists()
+        if options.command == 'init' and (options.template or options.source or options.repo or default_source):
+            from .sources import initialize
+            initialize(root, options.template, options.source, options.repo, options.ref, options.offline, options.config)
+            return 0
+        config_path = root / (options.config or 'delivery.yml')
+        platform_path = root / (options.platform or 'ci-platform.yml')
+        if options.format == "workflows":
+            from .workflows import compiler as workflow_compiler
+            from .workflows.models import Pipeline as WorkflowPipeline, Platform as WorkflowPlatform
+        if options.command == "init":
+            import yaml
+            if config_path.exists():
+                raise ValueError("configuration exists; init will not overwrite it")
+            ecosystem = {"python": {}} if options.ecosystem == "python" else {"node": {"package-manager": options.ecosystem}}
+            command = "uv run --no-sync pytest" if options.ecosystem == "python" else options.ecosystem + " run test"
+            example = {"version": 1, "projects": {"app": {"path": ".", **ecosystem,
+                "checks": {"unit": {"script": [command]}},
+                "workflows": {"push": {"checks": ["unit"]}, "merge-request": {"checks": ["unit"]}}}}}
+            config_path.write_text(yaml.safe_dump(example, sort_keys=False))
+            print(f"Created {config_path}; provide an internal platform configuration with --platform")
+            return 0
+        if options.command == "schema":
+            model = (WorkflowPlatform if options.platform_schema else WorkflowPipeline) if options.format == "workflows" else (Platform if options.platform_schema else Pipeline)
+            result = json.dumps(model.model_json_schema(by_alias=True), indent=2) + "\n"
+        else:
+            if options.format == "workflows":
+                if use_source:
+                    from .sources import load_project
+                    pipeline, platform, origins, inputs = load_project(root, options.config, options.platform, options.offline)
+                else:
+                    pipeline, platform = workflow_compiler.load(config_path, platform_path)
+                    origins = {"checks": "developer-defined; no hidden suites"}
+                    inputs = [config_path, platform_path]
+            else:
+                pipeline, platform, origins = load(config_path, platform_path)
+                inputs = [config_path, platform_path]
+            sources = source_hashes(root, inputs)
+            jobs, payload = (workflow_compiler.compile_pipeline(pipeline, platform, sources=sources) if options.format == "workflows" else compile_pipeline(pipeline, platform, sources=sources))
+            if options.command == "validate":
+                result = f"Valid: {len(pipeline.projects)} projects; {len(payload['nodes']) + 1} jobs. Target GitLab CI Lint is still required.\n"
+            elif options.command == "explain":
+                result = json.dumps({"generation": "committed top-level GitLab CI", "origins": origins,
+                                     "projects": payload["pipeline"]["projects"], "platform": payload["platform"], "jobs": payload["nodes"]}, indent=2) + "\n"
+            else:
+                if options.format == "workflows":
+                    import yaml
+                    result = "# Generated by generic-ci; edit delivery configuration and render again.\n" + yaml.safe_dump(jobs, sort_keys=False)
+                else:
+                    result = render(pipeline, platform, sources=sources)
+        if options.check:
+            if not options.output or not Path(options.output).is_file() or Path(options.output).read_text() != result:
+                raise ValueError("generated output differs; render again and commit it")
+            return 0
+        if options.output:
+            target = Path(options.output)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(result)
+        else:
+            print(result, end="")
+        return 0
+    except (ValueError, OSError, ValidationError) as error:
+        print(f"generic-ci: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

generic_ci/compiler.py

@@ -0,0 +1,242 @@
+"""Deterministic compilation to a committed, top-level GitLab pipeline."""
+import base64
+import hashlib
+import itertools
+import json
+import re
+from pathlib import Path
+
+import yaml
+
+from . import __version__
+
+
+def digest(value):
+    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def variants(native):
+    matrix = native.get("parallel")
+    if not matrix:
+        return [{}]
+    if set(matrix) != {"matrix"} or not isinstance(matrix["matrix"], list) or not matrix["matrix"]:
+        raise ValueError("gitlab.parallel must contain a nonempty native matrix list")
+    result = []
+    for row in matrix["matrix"]:
+        if not isinstance(row, dict) or not row:
+            raise ValueError("matrix rows must be nonempty mappings")
+        keys = list(row)
+        if any(not re.fullmatch(r"[A-Z][A-Z0-9_]*", k) or k.startswith(("CI_", "TOOLKIT_")) for k in keys):
+            raise ValueError("matrix keys must be uppercase and cannot use CI_ or TOOLKIT_ prefixes")
+        choices = [v if isinstance(v, list) else [v] for v in row.values()]
+        if any(not c or any(not isinstance(v, (str, int)) or isinstance(v, bool) for v in c) for c in choices):
+            raise ValueError("matrix values must be strings or integers (quote Python versions)")
+        for values in itertools.product(*choices):
+            result.append(dict(zip(keys, map(str, values))))
+            if len(result) > 200:
+                raise ValueError("matrix exceeds 200 combinations")
+    if len({json.dumps(v, sort_keys=True) for v in result}) != len(result):
+        raise ValueError("duplicate matrix combinations")
+    return result
+
+
+def compile_pipeline(pipeline, platform, *, sources=None):
+    data = pipeline.model_dump()
+    infra = platform.model_dump()
+    nodes = {}
+    refs = {}
+
+    def add(identifier, project, action, settings, *, native=None, variables=None):
+        if identifier in nodes:
+            raise ValueError(f"duplicate generated job {identifier}")
+        nodes[identifier] = {"project": project, "action": action, "settings": settings,
+                             "native": native or {}, "variables": variables or {}, "needs": []}
+        return identifier
+
+    def check_refs(project, names):
+        p = data["projects"][project]
+        selected = names if names is not None else [k for k, v in p["checks"].items() if v]
+        for required in infra["mandatory_checks"]:
+            if required not in selected:
+                raise ValueError(f"{project}: missing mandatory check {required}")
+        return [f"{project}.{name}" for name in selected]
+
+    for name, project in data["projects"].items():
+        for category in ("steps", "checks"):
+            for key, settings in project[category].items():
+                if settings is False:
+                    continue
+                public = f"{name}.{key}"
+                if public in refs or key in {"container", "package", "release"}:
+                    raise ValueError(f"{public}: check/step name collides with a public output")
+                rows = variants(settings["gitlab"])
+                if category == "steps" and settings["outputs"] and len(rows) > 1:
+                    raise ValueError(f"{public}: output-producing steps must have one variant; use separate named steps")
+                refs[public] = []
+                for index, variables in enumerate(rows):
+                    identifier = f"{name}-{key}" + (f"-{index + 1}" if len(rows) > 1 else "")
+                    refs[public].append(add(identifier, name, "step" if category == "steps" else "check", settings,
+                                            native=settings["gitlab"], variables=variables))
+        if project["package"] is not None:
+            refs[f"{name}.package"] = [add(f"{name}-package", name, "package", project["package"])]
+        if project["container"] is not None:
+            refs[f"{name}.container"] = [add(f"{name}-container", name, "container", project["container"])]
+        for key, deployment in project["deploy"].items():
+            add(f"{name}-deploy-{key}", name, "deploy", {**deployment, "name": key})
+            if deployment["preview"]:
+                add(f"{name}-stop-{key}", name, "stop", {**deployment, "name": key})
+        if project["release"]:
+            refs[f"{name}.release"] = [add(f"{name}-release", name, "release", project["release"])]
+
+    for identifier, node in nodes.items():
+        name = node["project"]
+        project = data["projects"][name]
+        settings = node["settings"]
+        requested = []
+        if node["action"] in {"step", "check", "container", "package"}:
+            requested += [r if "." in r else f"{name}.{r}" for r in settings.get("needs", [])]
+        if node["action"] in {"container", "package"}:
+            requested += check_refs(name, settings.get("checks"))
+        if node["action"] == "deploy":
+            requested += check_refs(name, settings["checks"])
+            images = settings["images"] or {name: {"repository": ["apps", name, "image", "repository"],
+                                                  "digest": ["apps", name, "image", "digest"]}}
+            settings["images"] = images
+            requested += [f"{p}.container" for p in images]
+        if node["action"] == "release":
+            requested += [f"{p}.release" for p in settings["needs"]]
+            requested += [f"{name}.{kind}" for kind in ("package", "container") if project[kind] is not None]
+            requested += check_refs(name, None)
+        for ref in dict.fromkeys(requested):
+            if ref not in refs:
+                raise ValueError(f"{identifier}.needs: unknown/disabled reference {ref}")
+            for upstream in refs[ref]:
+                if nodes[upstream]["native"].get("allow_failure"):
+                    raise ValueError(f"{identifier}: required check {ref} cannot allow failure")
+                node["needs"].append(upstream)
+        node["needs"] = sorted(set(node["needs"]))
+        if len(node["needs"]) >= 50:
+            raise ValueError(f"{identifier}: too many dependencies for supported GitLab needs limit")
+
+    visiting, visited = set(), set()
+
+    def visit(key):
+        if key in visiting:
+            raise ValueError(f"dependency cycle involving {key}")
+        if key in visited:
+            return
+        visiting.add(key)
+        for upstream in nodes[key]["needs"]:
+            visit(upstream)
+        visiting.remove(key)
+        visited.add(key)
+
+    for key in nodes:
+        visit(key)
+    # Selection follows actual cross-project graph edges as well as declared source dependencies.
+    for node in nodes.values():
+        if node["action"] == "release":
+            continue
+        project = data["projects"][node["project"]]
+        project["depends_on"] = sorted(set(project["depends_on"]) | {
+            nodes[k]["project"] for k in node["needs"] if nodes[k]["project"] != node["project"]})
+    if len(nodes) + 1 > platform.max_jobs:
+        raise ValueError(f"pipeline creates {len(nodes) + 1} jobs; platform limit is {platform.max_jobs}")
+    payload = {"version": __version__, "pipeline": data, "platform": infra, "nodes": nodes, "sources": sources or {}}
+    fingerprint = digest(payload)
+    encoded = base64.b64encode(json.dumps(payload, sort_keys=True).encode()).decode()
+    common_rules = [{"if": '$CI_PIPELINE_SOURCE == "merge_request_event"'}, {"if": "$CI_COMMIT_TAG"}, {"if": "$CI_COMMIT_BRANCH"}]
+    preview_rules = [{"if": '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_PROJECT_ID'}]
+    protected_rules = [{"if": '$CI_COMMIT_REF_PROTECTED == "true" && $CI_COMMIT_TAG'}]
+    default = infra["runtimes"]["default"]
+    output = {
+        "stages": ["prepare", "delivery"],
+        "workflow": {"auto_cancel": {"on_new_commit": "conservative"}, "rules": [
+            {"if": '$CI_PIPELINE_SOURCE == "merge_request_event"'}, {"if": "$CI_COMMIT_TAG"},
+            {"if": '$CI_PIPELINE_SOURCE == "push" && $CI_OPEN_MERGE_REQUESTS', "when": "never"},
+            {"if": "$CI_COMMIT_BRANCH"}, {"when": "never"}]},
+        "variables": {
+            "TOOLKIT_CONFIG_B64": encoded,
+            "CI_DEPENDENCY_OVERRIDES": {"value": "[]", "description": "Temporary JSON array of package/repository/ref/subdirectory overrides"},
+            "CI_DEPENDENCY_FILE": {"value": "", "description": "Optional override JSON file; exclusive with other override inputs"},
+            "CI_DEPENDENCY_REPO": {"value": "", "description": "Single candidate repository HTTPS URL"},
+            "CI_DEPENDENCY_REF": {"value": "", "description": "Single candidate branch, tag or SHA"},
+            "CI_DEPENDENCY_PACKAGE": {"value": "", "description": "Single candidate distribution name"},
+            "CI_DEPENDENCY_SUBDIRECTORY": {"value": "", "description": "Package path within candidate repository"},
+            "CI_FULL_PIPELINE": {"value": "false", "options": ["false", "true"], "description": "Run all projects regardless of changed paths"},
+        },
+        "toolkit-plan": {"stage": "prepare", "tags": default["tags"], "script": [f"python -m generic_ci.runtime plan {fingerprint}"],
+                         "rules": common_rules, "artifacts": {"paths": [".ci-out/plan.json"], "expire_in": infra["artifact_retention"]},
+                         "interruptible": True},
+    }
+    if default["image"]:
+        output["toolkit-plan"]["image"] = default["image"]
+    for identifier, node in nodes.items():
+        action = node["action"]
+        runtime_key = {"container": "build", "deploy": "helm", "stop": "helm", "release": "release"}.get(action, "default")
+        if action in {"check", "step"}:
+            runtime_key = node["settings"]["runtime"]
+            if runtime_key not in infra["runtimes"]:
+                raise ValueError(f"{identifier}.runtime: unknown runtime {runtime_key}")
+        runtime = infra["runtimes"].get(runtime_key, default)
+        native = node["native"]
+        node["shell"] = runtime["shell"]  # Set before final fingerprint below.
+        job = {"stage": "delivery", "tags": runtime["tags"], "interruptible": action in {"check", "step", "package"},
+               "script": [f"python -m generic_ci.runtime run {identifier} FINGERPRINT"],
+               "needs": [{"job": "toolkit-plan", "artifacts": True}] + [{"job": k, "artifacts": True, "optional": True} for k in node["needs"]],
+               "rules": common_rules, "allow_failure": native.get("allow_failure", False), "retry": 0,
+               "variables": {**native.get("variables", {}), **node["variables"]},
+               "artifacts": {"when": "always", "expire_in": infra["artifact_retention"], "paths": [f".ci-out/{identifier}/"]}}
+        if runtime["image"]:
+            job["image"] = runtime["image"]
+        for key in ("image", "tags", "services", "timeout", "rules", "cache", "resource_group"):
+            if native.get(key) is not None:
+                job[key] = native[key]
+        if node["settings"].get("junit"):
+            job["artifacts"]["reports"] = {"junit": [f".ci-out/{identifier}/reports/*.xml"]}
+        if action in {"deploy", "stop"}:
+            settings = node["settings"]
+            target = infra["targets"][settings["target"]]
+            preview = settings["preview"]
+            env = f"review/{node['project']}/{settings['name']}/$CI_MERGE_REQUEST_IID" if preview else f"{node['project']}/{settings['target']}"
+            job["environment"] = {"name": env, "url": target["url"], "deployment_tier": "development" if preview else ("production" if target["production"] else "staging")}
+            job["resource_group"] = env
+            job["rules"] = preview_rules if preview else (protected_rules if target["production"] else common_rules)
+            job["when"] = "manual" if action == "stop" else settings["when"]
+            if preview:
+                job["environment"].update({"on_stop": identifier.replace("-deploy-", "-stop-"), "auto_stop_in": settings["auto_stop_in"]})
+            if action == "stop":
+                job["environment"].pop("on_stop", None)
+                job["environment"].pop("auto_stop_in", None)
+                job["environment"]["action"] = "stop"
+                job["variables"]["GIT_STRATEGY"] = "none"
+                job["needs"] = []
+                job["allow_failure"] = True
+        if action == "release":
+            tag = node["settings"]["tag"]
+            pattern = re.escape(tag).replace(re.escape("{version}"), ".+").replace("/", "\\/")
+            job["rules"] = [{"if": f'$CI_COMMIT_REF_PROTECTED == "true" && $CI_COMMIT_TAG =~ /^{pattern}$/'}]
+            job["when"] = "manual"
+            job["resource_group"] = f"release/{node['project']}"
+            job["environment"] = {"name": f"publish/{node['project']}", "deployment_tier": "other"}
+        output[identifier] = job
+    # Shell metadata is also signed by the expected configuration fingerprint.
+    fingerprint = digest(payload)
+    encoded = base64.b64encode(json.dumps(payload, sort_keys=True).encode()).decode()
+    if len(encoded) > 100_000:
+        raise ValueError("compiled execution configuration exceeds 100 KB; split the pipeline into smaller project groups")
+    output["variables"]["TOOLKIT_CONFIG_B64"] = encoded
+    output["toolkit-plan"]["script"] = [f"python -m generic_ci.runtime plan {fingerprint}"]
+    for identifier in nodes:
+        output[identifier]["script"] = [f"python -m generic_ci.runtime run {identifier} {fingerprint}"]
+    return output, payload
+
+
+def render(pipeline, platform, *, sources=None):
+    jobs, _ = compile_pipeline(pipeline, platform, sources=sources)
+    return "# Generated by generic-ci; edit the project configuration and render again.\n" + yaml.safe_dump(jobs, sort_keys=False, width=120)
+
+
+def source_hashes(root, paths):
+    root = Path(root).resolve()
+    return {Path(path).resolve().relative_to(root).as_posix(): hashlib.sha256(Path(path).read_bytes()).hexdigest() for path in paths}

generic_ci/config.py

@@ -0,0 +1,148 @@
+"""Safe YAML loading, explicit preset expansion, and path/relationship validation."""
+import copy
+import fnmatch
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import yaml
+
+from .models import Pipeline, Platform, relative
+
+
+class UniqueLoader(yaml.SafeLoader):
+    pass
+
+
+def mapping(loader, node, deep=False):
+    result = {}
+    for key_node, value_node in node.value:
+        key = loader.construct_object(key_node, deep=deep)
+        if not isinstance(key, str):
+            raise ValueError(f"YAML mapping keys must be strings at line {key_node.start_mark.line + 1}")
+        if key in result:
+            raise ValueError(f"duplicate YAML key {key!r} at line {key_node.start_mark.line + 1}")
+        result[key] = loader.construct_object(value_node, deep=deep)
+    return result
+
+
+UniqueLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, mapping)
+
+
+def read_yaml(path):
+    text = Path(path).read_text()
+    if len(text) > 2_000_000:
+        raise ValueError("configuration exceeds 2 MB")
+    return yaml.load(text, Loader=UniqueLoader)
+
+
+def allowed_url(value, hosts, *, registry=False):
+    parsed = urlsplit("https://" + value if registry else value.replace("oci://", "https://", 1))
+    if parsed.scheme != "https" or parsed.hostname not in hosts or parsed.username or parsed.password or parsed.query:
+        raise ValueError(f"endpoint must use an allowed credential-free HTTPS host (host: {parsed.hostname})")
+
+
+def load(config_path, platform_path):
+    raw = read_yaml(config_path)
+    # Validate before merging so unknown keys cannot disappear through expansion.
+    declared = Pipeline.model_validate(raw)
+    effective = copy.deepcopy(raw)
+    origins = {}
+    for name, project in declared.projects.items():
+        row = effective["projects"][name]
+        if project.preset.startswith("python-"):
+            defaults = {"lint": {"script": ["uv run --no-sync ruff check ."]},
+                        "unit": {"script": ["uv run --no-sync pytest --junitxml=reports/junit.xml"],
+                                 "junit": ["reports/junit.xml"]}}
+            explicit = row.get("checks", {})
+            merged = {}
+            for check, settings in defaults.items():
+                override = explicit.get(check, {})
+                merged[check] = False if override is False else {**settings, **override}
+                origins[f"projects.{name}.checks.{check}"] = "project" if check in explicit else project.preset
+            row["checks"] = {**merged, **{k: v for k, v in explicit.items() if k not in defaults}}
+            row.setdefault("dependencies", {"manager": "uv"})
+            if project.preset == "python-package":
+                row.setdefault("package", {})
+            else:
+                row.setdefault("container", {})
+        else:
+            row.setdefault("dependencies", {"manager": "none"})
+    pipeline = Pipeline.model_validate(effective)
+    platform = Platform.model_validate(read_yaml(platform_path))
+    for runtime in platform.runtimes.values():
+        if runtime.image:
+            allowed_url(runtime.image, platform.allowed_hosts, registry=True)
+    for registry in (platform.registry, platform.preview_registry):
+        allowed_url(registry, platform.allowed_hosts, registry=True)
+    if platform.registry.rstrip("/") == platform.preview_registry.rstrip("/"):
+        raise ValueError("preview-registry must be separate from registry")
+    if platform.chart.startswith("oci://"):
+        allowed_url(platform.chart, platform.allowed_hosts)
+    else:
+        relative(platform.chart)
+    for name, project in pipeline.projects.items():
+        for check_name, check in project.checks.items():
+            if check and not check.script:
+                raise ValueError(f"projects.{name}.checks.{check_name}.script: required for a custom check")
+        for check in [*project.checks.values(), *project.steps.values()]:
+            if check and check.gitlab.image:
+                allowed_url(check.gitlab.image, platform.allowed_hosts, registry=True)
+        for dependency in project.depends_on:
+            if dependency not in pipeline.projects:
+                raise ValueError(f"projects.{name}.depends-on: unknown project {dependency}")
+        for mandatory in platform.mandatory_checks:
+            if not project.checks.get(mandatory):
+                raise ValueError(f"projects.{name}.checks.{mandatory}: platform-required check is missing/disabled")
+        if project.container and project.container.repository:
+            allowed_url(project.container.repository, platform.allowed_hosts, registry=True)
+        for dep_name, deployment in project.deploy.items():
+            prefix = f"projects.{name}.deploy.{dep_name}"
+            if deployment.target not in platform.targets:
+                raise ValueError(f"{prefix}.target: unknown target {deployment.target}")
+            if deployment.preview and platform.targets[deployment.target].production:
+                raise ValueError(f"{prefix}: previews require a nonproduction target")
+            if deployment.chart:
+                if deployment.chart.startswith("oci://"):
+                    allowed_url(deployment.chart, platform.allowed_hosts)
+                    if not deployment.chart_version:
+                        raise ValueError(f"{prefix}: custom OCI chart requires chart-version")
+                else:
+                    relative(deployment.chart)
+                if not deployment.images:
+                    raise ValueError(f"{prefix}.images: custom chart requires explicit image bindings")
+            checks = deployment.checks if deployment.checks is not None else [k for k, v in project.checks.items() if v]
+            for check in checks:
+                if not project.checks.get(check):
+                    raise ValueError(f"{prefix}.checks: unknown or disabled check {check}")
+            if not set(platform.mandatory_checks) <= set(checks):
+                raise ValueError(f"{prefix}.checks: cannot remove platform-required checks")
+            for source in deployment.images:
+                if source not in pipeline.projects or not pipeline.projects[source].container:
+                    raise ValueError(f"{prefix}.images: {source} is not a container project")
+        if project.release:
+            for dep in project.release.needs:
+                if dep not in pipeline.projects or not pipeline.projects[dep].release:
+                    raise ValueError(f"projects.{name}.release.needs: unknown release {dep}")
+                if pipeline.projects[dep].release.tag != project.release.tag:
+                    raise ValueError(f"projects.{name}.release.needs: same-pipeline release dependencies require a common tag convention")
+    owners = [p.release.tag for p in pipeline.projects.values() if p.release and p.release.gitlab_release]
+    if len(owners) != len(set(owners)):
+        raise ValueError("a shared release tag must have exactly one gitlab-release owner")
+    return pipeline, platform, origins
+
+
+def affected(pipeline, changed):
+    """None means unavailable baseline: full run. Empty means no source change."""
+    if changed is None:
+        return set(pipeline["projects"])
+    selected = set()
+    for name, project in pipeline["projects"].items():
+        root = project["path"].rstrip("/")
+        for path in changed:
+            if root == "." or path == root or path.startswith(root + "/") or any(fnmatch.fnmatchcase(path, pat) for pat in project["watch"]):
+                selected.add(name)
+    while True:
+        expanded = selected | {name for name, p in pipeline["projects"].items() if set(p["depends_on"]) & selected}
+        if expanded == selected:
+            return selected
+        selected = expanded