docker-devkit 0.2.1.dev37485576216__tar.gz → 0.3.0__tar.gz

docker_devkit-0.3.0/.github/workflows/integrate.yml

@@ -0,0 +1,24 @@
+name: Integrate
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: [dev]
+
+concurrency:
+  group: integrate-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  preflight:
+    uses: outernet-foundation/github-actions-toolkit/.github/workflows/preflight.yml@66df38b08b8209b587de1c140b720d835ed8a3c3
+
+  update-pr-draft-release:
+    needs: [preflight]
+    permissions:
+      contents: write
+      packages: read
+    uses: outernet-foundation/github-actions-toolkit/.github/workflows/update-pr-draft-release.yml@66df38b08b8209b587de1c140b720d835ed8a3c3

docker_devkit-0.3.0/.github/workflows/merge-gate.yml

@@ -0,0 +1,18 @@
+name: Merge gate
+
+on:
+  pull_request:
+    branches: [dev]
+    types: [labeled]
+
+concurrency:
+  group: merge-gate-${{ github.event.pull_request.number }}
+
+permissions:
+  contents: read
+
+jobs:
+  merge-gate:
+    uses: outernet-foundation/github-actions-toolkit/.github/workflows/merge-gate.yml@66df38b08b8209b587de1c140b720d835ed8a3c3
+    secrets:
+      merge-bot-private-key: ${{ secrets.MERGE_BOT_APP_PRIVATE_KEY }}

docker_devkit-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    branches: [main, dev]
+
+concurrency:
+  group: release-${{ github.ref }}
+
+permissions:
+  contents: read
+
+jobs:
+  prerelease:
+    if: github.ref == 'refs/heads/dev'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: outernet-foundation/github-actions-toolkit/.github/actions/release@66df38b08b8209b587de1c140b720d835ed8a3c3
+        with:
+          channel: dev
+
+  release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: outernet-foundation/github-actions-toolkit/.github/actions/release@66df38b08b8209b587de1c140b720d835ed8a3c3
+        with:
+          channel: stable

{docker_devkit-0.2.1.dev37485576216 → docker_devkit-0.3.0}/AGENTS.md

@@ -4,13 +4,13 @@
 
 `docker-devkit` owns the Docker-stack lifecycle commands — `up`, `down`, `build`, `mirror`, `generate-score`, `docker-build-matrix` — plus the helpers they share (`detect_gpu`, `modes`, `context_sha`). A small, generic package that any repo shipping a compose graph can depend on to get the same bring-up/tear-down / cross-build flow, with the compose assembly declared per consumer in the `lifecycle:` section of `docker-devkit.yaml`. The PyPI identity starts its own version tags at `0.1.0`; the terminal `stack-toolkit` distributions (≤0.1.1) are deprecation signposts pointing here, not this package's history.
 
-The package is `docker_devkit` (src-layout under `src/docker_devkit/`); all dependencies resolve from PyPI — `bashrun` (shell-outs), `ci-devkit` (builds-shelf push for CI lock artifacts), `packaging` (`requires` specifier parsing), `pathspec`, `pydantic`/`pydantic-settings`, `pyyaml` (score-document parsing), `strictyaml` (config loading), `typer` (CLIs) — git-source pins only in scratch branches testing unreleased changes.
+The package is `docker_devkit` (src-layout under `src/docker_devkit/`); all dependencies resolve from PyPI — `bashrun` (shell-outs), `build-artifact-registry` (builds-shelf push and ORAS provisioning for CI artifacts), `packaging` (`requires` specifier parsing), `pathspec`, `pydantic`/`pydantic-settings`, `pyyaml` (score-document parsing), `strictyaml` (config loading), `typer` (CLIs) — git-source pins only in scratch branches testing unreleased changes.
 
-Config follows the org law (home: release-devkit's `AGENTS.md`): this is a root-`docker-devkit.yaml` devkit. The schema (`config.DockerDevkitConfig`, strictyaml-loaded, `extra="forbid"` on every model) carries a required `requires` version stamp plus optional `lifecycle` / `mirror` / `generate-score` sections; `config.load_config` self-checks the installed docker-devkit version against `requires` and refuses loudly outside the range (the `0.0.0.dev0` dev sentinel bypasses the check, not the field).
+Config follows the org law (home: github-actions-toolkit's `AGENTS.md`): this is a root-`docker-devkit.yaml` devkit. The schema (`config.DockerDevkitConfig`, strictyaml-loaded, `extra="forbid"` on every model) carries a required `requires` version stamp plus optional `lifecycle` / `mirror` / `generate-score` sections; `config.load_config` self-checks the installed docker-devkit version against `requires` and refuses loudly outside the range (the `0.0.0.dev0` dev sentinel bypasses the check, not the field).
 
 ## Release flow
 
-release-devkit's `AGENTS.md` owns the three-workflow contract; this repo follows it unchanged. Repo-specific facts: release-devkit is never a project dependency (docker-devkit sits inside its own dependency graph; a project-level edge is a resolver cycle), and from 1.0 on API-breaking changes ship with a manually bumped `major_minor` (pre-1.0, breaking changes ride the patch flow; patch-auto assumes additive changes).
+github-actions-toolkit's `AGENTS.md` owns the consumer workflow contract; this repo follows it unchanged. Repo-specific facts: github-actions-toolkit is never a project dependency (docker-devkit sits inside its own dependency graph; a project-level edge is a resolver cycle), and from 1.0 on API-breaking changes ship with a manually bumped `major_minor` (pre-1.0, breaking changes ride the patch flow; patch-auto assumes additive changes).
 
 ## Mirror consumption
 
@@ -24,12 +24,12 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 |---|---|
 | `up.py` | `docker compose up`. Flags: `--attached`/`-a`, `--quiet-pull`/`-q`, `--build`, `--gpu auto\|cuda\|rocm\|none`, `--dev`, `--allow-upstream-fallback`. |
 | `down.py` | `docker compose down`. Flags: `--volumes`/`-v` (also removes named volumes), `--gpu`. |
-| `build_docker.py` | `run_build()` + the `build` command — cross-builds all images per the resolved image manifest, writing the paired lock (one `NAME=path:tag@sha256:…` entry per `x-base-images` declaration; `@digest`-pinned declarations pass through unresolved; mirror-prefixed declarations resolve their digest against the upstream reference). `--mode ci` hard-requires `x-registry-cache` in the manifest. |
+| `build_docker.py` | `run_build()` + the `build` command — cross-builds all images per the resolved image manifest, writing the paired lock (one `NAME=path:tag@sha256:…` entry per `x-base-images` declaration; `@digest`-pinned declarations pass through unresolved; mirror-prefixed declarations resolve their digest against the upstream reference). `--push` is the CI shape (push images + registry caches + digest-manifest shelving) and hard-requires `x-registry-cache`; the flag order mirrors the binding's run line (`--push`, `--targets`, `--gpu`), and `--targets` accepts both repeated flags and one space-joined value. Push mode reads its registry facts from the neutral `REGISTRY`/`REGISTRY_TOKEN`/`REGISTRY_USERNAME` environment — no `GITHUB_*` reads. |
 | `score_generate.py` | `generate-score` — deterministic Score-manifest generation from a consumer's `stack/score/` sources: `${ALL_CAPS}` placeholder expansion into tempdir-rendered workload copies, idempotent `score-compose`/`score-k8s` init (state preserved across runs), and a determinism suite (document sort, state-path normalisation, 0644 modes, LF newlines). Consumer policy — workloads, provisioners, patch templates, output paths, storage classes, publishes, tool versions — is declared in the consumer's root `docker-devkit.yaml` under `generate-score:` (`ScoreConfig`, model in `config.py`); `load_score_config()` reads it, `ensure_score_tools()` fetches the pinned score-compose/score-k8s release binaries (for CI staleness gates). Output and state paths resolve against the repo root: the compose half runs in `score_dir` (its `.score-compose` state stays there, gitignored), the k8s half runs in the configured `k8s_state` parent so the committed `.score-k8s` state lands in the generated tier. `--local` writes the k8s artifact to the configured gitignored local path with the local storage class. |
 | `config.py` | `DockerDevkitConfig` — the root `docker-devkit.yaml` schema: a required `requires` PEP 440 specifier plus optional `lifecycle` / `mirror` / `generate-score` sections, `extra="forbid"` on every model. `load_config(root)` is the single strictyaml entry point: parses the file (returns `None` when absent — the no-config → single-file-default path for `up`/`down`), then self-checks the installed docker-devkit version against `requires` (refuses loudly outside range; the `0.0.0.dev0` dev sentinel bypasses the check, not the field). The section models (`LifecycleConfig`, `MirrorConfig`, `ScoreConfig`) live here; `load_lifecycle_config` / `load_mirror_config` / `load_score_config` in their modules are thin wrappers over it. |
 | `lifecycle.py` | `LifecycleConfig` (model in `config.py`) — the `lifecycle:` section declaration (`files`: compose files in layering order with `{gpu}` templating; `dev_file`: optional dev overlay); `load_lifecycle_config()` (reads the `lifecycle:` section via `config.load_config`, `None` when the section or file is absent), `resolve_manifest()` / `require_manifest()` (the raising form) / `resolve_lock()` (the image manifest and its lock are a named pair — `workloads/images.yml` + `workloads/images.lock`, with the legacy root `compose.bake.yml` + `.env.lock` pair still resolved so repos can upgrade before moving files), `enforce_bake_declaration()` (a manifest under either name requires a declaration), `expand_compose_files()` (assembles the `-f` list; a `{gpu}` entry is dropped when the GPU resolves to `none`; `dev_file` appended when a dev overlay applies). |
 | `detect_gpu.py` | `detect_gpu()` → `cuda`/`rocm`/`none` from host devices; the `Gpu` literal. |
-| `matrix.py` | `docker-build-matrix` — emit the CI build matrix as one `matrix=<JSON>` `$GITHUB_OUTPUT` line: one entry per variant (`common`/`cuda`/`rocm`, derived from the service-name suffix convention), `targets` = that variant's explicitly-buildable services with dependents grouped with the base their `additional_contexts: target:` references pull in (one leg builds a whole dependency-closure group in a single bake invocation — the safe default over hoping registry cache makes flat legs suffice). Tagless services never become explicit targets (bake rejects a tagless target under `--push`) — they ride as in-invocation dependencies; `x-cross-compile-targets` are excluded; a group spanning variants is a loud error. |
+| `matrix.py` | `docker-build-matrix` — emit the CI build leg list as a bare JSON array on stdout (the binding's getter pipes it through its `matrix` verb, which composes the envelope and guards the empty case): one entry per variant × cohort cell, `targets` = that cell's explicitly-buildable services with dependents grouped with the base their `additional_contexts: target:` references pull in (one leg builds a whole dependency-closure group in a single bake invocation). The leg schema — `targets` (space-joined), `variant` (`common`/`cuda`/`rocm`, from the service-name suffix) — is named contract with the binding; renaming a key breaks its fanout YAML. The cross-compile cohort (services in `x-cross-compile-targets` or declaring `platforms:`) gets its own legs — per-arch builds are the QEMU-slow ones and parallelize away from native builds; a group spanning cohort membership is a loud error. Tagless services never become explicit targets (bake rejects a tagless target under `--push`) — they ride as in-invocation dependencies; a group spanning gpu variants is a loud error. |
 | `modes.py` | `resolve_auth_mode()` — validates `PUBLIC_URL` + `AUTH_MODE` from `.env`, rejecting `keycloak` over cleartext `http://`. |
 | `context_sha.py` | `compute_service_shas(repo_root, bake: BakeDocument)` — per-service `tree-<hash>` image tags over the `.dockerignore`-allowlisted git tree. The workload-tree root is derived as the single top-level directory containing every tagged service's Dockerfile (a bake graph spanning several top-level directories is a loud error); files under it that belong to no tagged service are excluded from every SHA rather than shared into all of them. |
 | `documents.py` | `BakeDocument` + `parse_bake(path)` — the typed bake-file model every consumer of bake data goes through (build, up, down, generate-score, the reference collectors). A field validator enforces at parse time that every `x-base-images` value is `path:tag` or `path@digest` (a `${…}` hole or a bare path is a validation error, killing the silent-unpinned `FROM` → `:latest` failure mode). `digest_pinned(reference)` is the shared tail test. |
@@ -62,10 +62,10 @@ The mirror is declared, not inferred: the `mirror:` section with `prefix` in the
 
 - `build` resolves lock digests for mirror-prefixed declarations against the upstream reference (prefix stripped, tag/digest tail preserved) and records it under the mirror name. Valid because `crane copy` produces byte-identical manifests — upstream and mirror digests are the same digest; a manifest re-wrap (`docker buildx imagetools`-shaped tooling) would change the top-level digest and break lock equality. This makes declare → re-lock walkable before CI has mirrored anything; lock lines are never hand-authored.
 - `up` fails closed: after lock resolution it probes each mirror-prefixed lock entry; a missing mirror image is a hard `RuntimeError`, not a warning — people ignore warnings, and warnings are errors someone was too lazy to fix. The only escape is the per-run `--allow-upstream-fallback` flag. Under the flag, missing entries become digest-preserving address substitutions (same bytes from the upstream host), printed as plain statements — the operator asked for fallback, the run reports what it did. The rewrite is authoritative on both consumption paths: an appended `--env-file` overlay (compose's later env files win) plus `os.environ` before `build`'s bake (shell env wins over env files; `run_build` re-applies the overlay after its own lock update so bake is never clobbered). CI never passes the flag — the mirror job runs before anything needs the images.
-- The `mirror` verb (crane install from a pinned release, per-target `crane copy`, count footer) uses bashrun + plain prints, deliberately not ci-devkit's `ci_step` — it needs nothing from the floor.
+- The `mirror` verb (crane install from a pinned release, per-target `crane copy`, count footer) uses bashrun + plain prints — it needs nothing from any runner floor.
 - Non-mirror lock entries (e.g. `placeframe/*` publishes) are not probed and keep failing naturally at pull. There is no config-level ban on the flag: an air-gap fails closed anyway (no route to upstream — the pull dies with or without it).
 
-The ci-devkit edge exists for the builds shelf: a CI `build` run distills bake's `--metadata-file` into a digest manifest (`target → {ref, digest, tags[]}` JSON) and pushes it to the repo's builds registry at the conventional `images-digests/all` project/platform (`--builds-registry` + `--run-number`) through ci-devkit's `push_build` — one `images-digests-all` artifact tagged `run-{N}` per run, consumed by release-devkit's release surfaces for the built-image digest table. `workloads/images.lock` stays in source control (the stapler that consumed the shelf copy is gone). ORAS CLI knowledge lives only in ci-devkit (org law); local builds (`--mode local`, no `--builds-registry`) never touch it.
+The build-artifact-registry edge exists for the builds shelf: a `build --push` run distills bake's `--metadata-file` into a digest manifest (`target → {ref, digest, tags[]}` JSON) and pushes it through build-artifact-registry's `push_build` — one **shard** per matrix leg, tagged `sha-{full}-{key}` where the key is the sha256-8 of the leg's sorted targets (legs run in parallel, so a shared tag would be last-writer-wins; the pull side enumerates a SHA's shards and merges, and consumption only ever runs after every leg finished). The shelf root comes from the neutral `REGISTRY` environment and the SHA from the checkout HEAD (`git rev-parse HEAD`), stamping the certified PR head the release channels query back at; the keying law is stated in github-actions-toolkit's `AGENTS.md`. `workloads/images.lock` stays in source control (the stapler that consumed the shelf copy is gone). ORAS CLI knowledge lives only in build-artifact-registry (org law); local builds (no `--push`) never touch the shelf.
 
 Lifecycle stays a separate package from codegen (client generation, datamodel generation, workspace locking) because their dependency surfaces are disjoint — bundling them would force a consumer that only brings a stack up to install `sqlacodegen`, `psycopg`, `datamodel-code-generator`.
 

{docker_devkit-0.2.1.dev37485576216 → docker_devkit-0.3.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: docker-devkit
-Version: 0.2.1.dev37485576216
+Version: 0.3.0
 Summary: Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly
 License-File: LICENSE
 License-File: NOTICE
 Requires-Python: >=3.13
 Requires-Dist: bashrun>=0.1.0
-Requires-Dist: ci-devkit>=0.1.15
+Requires-Dist: build-artifact-registry>=0.2.0.dev0
 Requires-Dist: packaging>=24.1
 Requires-Dist: pathspec>=1.0.4
 Requires-Dist: pydantic-settings>=2.9.1

{docker_devkit-0.2.1.dev37485576216 → docker_devkit-0.3.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "docker-devkit"
-version = "0.2.1.dev37485576216"
+version = "0.3.0"
 description = "Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly"
 requires-python = ">=3.13"
 dependencies = [
     "bashrun>=0.1.0",
-    "ci-devkit>=0.1.15",
+    "build-artifact-registry>=0.2.0.dev0",
     "packaging>=24.1",
     "pathspec>=1.0.4",
     "pydantic>=2.11.7",
@@ -20,7 +20,7 @@ dev = [
     "basedpyright>=1.39.10",
     "ruff>=0.14.11",
     "pytest>=8.0.0",
-    "python-devkit>=0.1.0",
+    "python-devkit>=0.3.0.dev0",
     "types-pyyaml>=6.0.12.20260906",
     "types-strictyaml>=1.7.3.3",
 ]
@@ -39,7 +39,6 @@ docker-build-matrix = "docker_devkit.matrix:app"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/docker_devkit"]
-include = ["src/docker_devkit/py.typed"]
 
 [tool.uv.sources]
 

docker_devkit-0.3.0/release-devkit.yaml

@@ -0,0 +1,6 @@
+packages:
+  docker-devkit:
+    path: .
+    major_minor: "0.3"
+    registry: pypi
+    identity: docker-devkit

docker_devkit-0.3.0/scripts/preflight.py

@@ -0,0 +1,3 @@
+from bashrun.bash import bash
+
+bash("uv run --locked preflight-python")

{docker_devkit-0.2.1.dev37485576216 → docker_devkit-0.3.0}/src/docker_devkit/build_docker.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import platform
@@ -7,11 +8,12 @@ import re
 from pathlib import Path
 from subprocess import CalledProcessError
 from tempfile import TemporaryDirectory
-from typing import Annotated, Any, Literal, TypedDict
+from typing import Annotated, Any, TypedDict
 
 import typer
 from bashrun.bash import bash, bash_output
-from ci_devkit.builds import push_build
+from build_artifact_registry.builds import push_build
+from build_artifact_registry.setup_oras import install_oras
 from .detect_gpu import GPU_TYPES, Gpu, detect_gpu
 from .documents import BakeDocument, digest_pinned, parse_bake
 from pydantic_settings import BaseSettings
@@ -31,8 +33,6 @@ settings = Settings.model_validate({})
 
 METADATA_PATH = Path("metadata.json")
 
-Mode = Literal["local", "ci"]
-
 DIGEST_PROJECT = "images-digests"
 DIGEST_PLATFORM = "all"
 DIGEST_FILE_NAME = "images-digests.json"
@@ -49,55 +49,43 @@ app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
 
 @app.command()
 def build(
+    push: Annotated[
+        bool, typer.Option("--push", help="Push images (+ registry caches) and shelve the digest manifest.")
+    ] = False,
+    targets_opt: Annotated[
+        list[str] | None,
+        typer.Option("--targets", "-t", help="Build only these services (from the image manifest)."),
+    ] = None,
+    gpu: Annotated[Gpu, typer.Option("--gpu", help="auto|cuda|rocm|none")] = "auto",
     upgrade: bool = typer.Option(False, "--upgrade", "-u", help="Re-resolve and rewrite base digests."),
     lock_only: bool = typer.Option(False, "--lock-only", help="Update lock file without building images."),
-    mode: Annotated[
-        Mode, typer.Option("--mode", help="local: --load images; ci: --push images + registry caches.")
-    ] = "local",
-    gpu: Annotated[Gpu, typer.Option("--gpu", help="auto|cuda|rocm|none")] = "auto",
     gpu_only: bool = typer.Option(
         False, "--gpu-only", help="Build only the services suffixed for this gpu (requires a concrete --gpu)."
     ),
     no_cache: bool = typer.Option(False, "--no-cache", help="Force rebuild by disabling cache usage."),
-    targets_opt: Annotated[
-        list[str] | None,
-        typer.Option("--targets", "-t", help="Build only these services (from the image manifest)."),
-    ] = None,
-    builds_registry: Annotated[
-        str | None,
-        typer.Option(
-            "--builds-registry", help="OCI registry path to push the digest manifest to (CI build artifacts)."
-        ),
-    ] = None,
-    run_number: Annotated[
-        int, typer.Option("--run-number", help="CI run number baked into the digest manifest's builds-shelf tag.")
-    ] = 0,
 ) -> None:
+    targets = [service for value in targets_opt or [] for service in value.split()] or None
     run_build(
+        push=push,
+        targets_opt=targets,
+        gpu=gpu,
         upgrade=upgrade,
         lock_only=lock_only,
-        mode=mode,
-        gpu=gpu,
         gpu_only=gpu_only,
         no_cache=no_cache,
-        targets_opt=targets_opt,
-        builds_registry=builds_registry,
-        run_number=run_number,
     )
 
 
 def run_build(
     *,
+    push: bool = False,
+    targets_opt: list[str] | None = None,
+    gpu: Gpu = "auto",
     upgrade: bool = False,
     lock_only: bool = False,
-    mode: Mode = "local",
-    gpu: Gpu = "auto",
     gpu_only: bool = False,
     no_cache: bool = False,
-    targets_opt: list[str] | None = None,
     env_overlay: dict[str, str] | None = None,
-    builds_registry: str | None = None,
-    run_number: int = 0,
 ) -> None:
     root = Path.cwd()
     manifest = require_manifest(root)
@@ -112,18 +100,17 @@ def run_build(
     # Load any existing lock
     lock_data = parse_env_file(lock_file) if lock_file.exists() else {}
 
-    # TOOD: Create separate commands for ci and local modes so typer can do this validation instead of us
-    if mode == "ci" and gpu == "auto":
-        raise typer.BadParameter("In CI mode, --gpu cannot be 'auto'; specify 'cuda' or 'rocm'.")
+    if push and gpu == "auto":
+        raise typer.BadParameter("With --push, --gpu cannot be 'auto'; specify 'cuda' or 'rocm'.")
 
-    if mode == "ci" and bake.registry_cache is None:
-        raise typer.BadParameter("In CI mode, the bake file must declare x-registry-cache.")
+    if push and bake.registry_cache is None:
+        raise typer.BadParameter("With --push, the bake file must declare x-registry-cache.")
 
     if gpu_only and gpu not in GPU_TYPES:
         raise typer.BadParameter("--gpu-only requires a concrete gpu (cuda or rocm), not 'auto' or 'none'.")
 
     # For local builds, ensure Docker GC limits are high enough that GPU builds don't cause cache evictions
-    if mode == "local" and not lock_only and not targets_opt:
+    if not push and not lock_only and not targets_opt:
         _check_gc_limits(min_gb=60)
 
     # Resolve gpu
@@ -175,8 +162,8 @@ def run_build(
     else:
         targets = compute_default_targets(bake, gpu, gpu_only)
 
-    # Configure registry caches in CI mode
-    if mode == "ci":
+    # Configure registry caches for push builds
+    if push:
         for target in targets:
             target_cache = f"{bake.registry_cache}:{target}"
             command_arguments.append(
@@ -186,9 +173,9 @@ def run_build(
 
     # `docker buildx --load` only writes a single arch to the host image store,
     # so bake targets declared multi-platform get overridden to host arch in
-    # local builds. CI uses `--push` and produces the full manifest list.
+    # local builds. --push produces the full manifest list.
     # Override key is `platform` (singular) even though the bake field is plural.
-    if mode == "local":
+    if not push:
         machine = platform.machine().lower()
         if machine in ("x86_64", "amd64"):
             host_platform = "linux/amd64"
@@ -200,8 +187,8 @@ def run_build(
             if len(bake.services[target].build.platforms) > 1:
                 command_arguments.append(f"--set {target}.platform={host_platform}")
 
-    # Load or push images based on mode
-    command_arguments.append("--load" if mode == "local" else "--push")
+    # Load or push images
+    command_arguments.append("--push" if push else "--load")
 
     # Handle no-cache option
     if no_cache:
@@ -229,28 +216,39 @@ def run_build(
     if not set(targets) <= baked_images.keys():
         raise RuntimeError("Bake output does not cover the requested targets")
 
-    push_image_digests(builds_registry, run_number, baked_images, targets)
+    # Push the digest manifest to the repo's builds shelf (registry supplied explicitly, SHA from the checkout)
+    if push:
+        registry = os.environ.get("REGISTRY", "")
+        if not registry:
+            raise SystemExit("REGISTRY not set — --push shelves the digest manifest under it")
+        shelf = f"{registry}/builds"
+        sha = bash_output("git rev-parse HEAD").strip()
+        push_image_digests(shelf, sha, baked_images, targets)
+
 
+def leg_key(targets: list[str]) -> str:
+    return hashlib.sha256(",".join(sorted(targets)).encode("utf-8")).hexdigest()[:8]
 
+
+# Each matrix leg pushes its own manifest shard under sha-{sha}-{key}: legs run in
+# parallel, so a shared tag would be last-writer-wins. The pull side enumerates a
+# SHA's shards and merges — consumption happens only after every leg finished.
 def push_image_digests(
-    builds_registry: str | None,
-    run_number: int,
+    shelf: str,
+    sha: str,
     baked_images: dict[str, Any],
     targets: list[str],
 ) -> None:
-    if builds_registry is None:
-        return
-    if run_number <= 0:
-        raise typer.BadParameter("--builds-registry requires a positive --run-number")
+    install_oras()
     manifest = distill_digest_manifest(baked_images, targets)
     with TemporaryDirectory(prefix="digest-manifest-") as staging:
         manifest_path = Path(staging) / DIGEST_FILE_NAME
         manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
         push_build(
-            builds_registry,
+            shelf,
             DIGEST_PROJECT,
             DIGEST_PLATFORM,
-            f"run-{run_number}",
+            f"sha-{sha}-{leg_key(targets)}",
             Path(staging),
             [DIGEST_FILE_NAME],
         )
@@ -271,6 +269,8 @@ def distill_digest_manifest(baked_images: dict[str, Any], targets: list[str]) ->
             if separator:
                 image_ref = repository
                 tags.append(tag)
+        if not tags:
+            raise ValueError(f"target '{target}' produced no tagged image references from '{image_name}'")
         manifest[target] = {"ref": image_ref, "digest": digest, "tags": tags}
     return manifest
 

{docker_devkit-0.2.1.dev37485576216 → docker_devkit-0.3.0}/src/docker_devkit/image_refs.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-import datetime
+import datetime as dt
 import re
 import shlex
 import tomllib
@@ -21,17 +21,7 @@ DIGEST_PATTERN = re.compile(r"^Digest:\s+(sha256:[a-f0-9]+)", re.MULTILINE)
 MISSING_VERSION = "<missing>"
 
 
-type TomlValue = (
-    str
-    | int
-    | float
-    | bool
-    | datetime.datetime
-    | datetime.date
-    | datetime.time
-    | list[TomlValue]
-    | dict[str, TomlValue]
-)
+type TomlValue = str | int | float | bool | dt.datetime | dt.date | dt.time | list[TomlValue] | dict[str, TomlValue]
 
 
 class TomlDocument(RootModel[TomlValue]):

{docker_devkit-0.2.1.dev37485576216 → docker_devkit-0.3.0}/src/docker_devkit/matrix.py

@@ -18,32 +18,49 @@ PLAIN_VARIANT = "common"
 @app.command()
 def matrix_main() -> None:
     bake = parse_bake(require_manifest(Path.cwd()))
-    print(f"matrix={json.dumps({'include': compute_matrix_entries(bake)})}")
+    print(json.dumps(compute_matrix_entries(bake)))
 
 
-# One entry per variant: targets are the dependency-closure groups of that variant's
-# explicitly-buildable services, coalesced into a single leg — the shape a single
-# gpu-resolved build invocation would produce, with dependents grouped with the base
-# their additional_contexts `target:` references pull in.
+# One entry per variant and cohort cell: targets are the dependency-closure groups
+# of that cell's explicitly-buildable services, coalesced into a single leg — the
+# shape a single gpu-resolved build invocation would produce, with dependents
+# grouped with the base their additional_contexts `target:` references pull in.
+# The cross-compile cohort gets its own legs: per-arch builds are the QEMU-slow
+# ones, so they parallelize away from native builds instead of serializing them
+# into one invocation.
 def compute_matrix_entries(bake: BakeDocument) -> list[dict[str, str]]:
-    entries_by_variant: dict[str, list[str]] = {}
+    cohort = cross_compile_cohort(bake)
+    entries_by_cell: dict[tuple[str, bool], list[str]] = {}
     for group in dependency_groups(bake):
-        explicit = sorted(
-            service
-            for service in group
-            if bake.services[service].build.tags and service not in set(bake.cross_compile_targets)
-        )
+        explicit = sorted(service for service in group if bake.services[service].build.tags)
         if not explicit:
             continue
         variant = group_variant(bake, explicit)
-        entries_by_variant.setdefault(variant, []).extend(explicit)
+        memberships = {service in cohort for service in explicit}
+        if len(memberships) > 1:
+            raise RuntimeError(
+                f"dependency group spans cross-compile cohort membership ({', '.join(explicit)}) — "
+                "additional_contexts must stay within one cohort"
+            )
+        entries_by_cell.setdefault((variant, memberships.pop()), []).extend(explicit)
 
     return [
-        {"targets": " ".join(sorted(entries_by_variant[variant])), "variant": variant}
-        for variant in sorted(entries_by_variant)
+        {"targets": " ".join(sorted(targets)), "variant": variant}
+        for (variant, _), targets in sorted(entries_by_cell.items())
     ]
 
 
+# The cross-compile cohort: every service declaring `platforms:` (per-arch
+# treatment is a manifest fact, not an operator judgment) plus the hand-listed
+# x-cross-compile-targets members.
+def cross_compile_cohort(bake: BakeDocument) -> set[str]:
+    unknown = set(bake.cross_compile_targets) - set(bake.services)
+    if unknown:
+        raise RuntimeError(f"x-cross-compile-targets names unknown services: {', '.join(sorted(unknown))}")
+    pinned = {service for service, config in bake.services.items() if config.build.platforms}
+    return pinned | set(bake.cross_compile_targets)
+
+
 def dependency_groups(bake: BakeDocument) -> list[list[str]]:
     parent = {service: service for service in bake.services}
 

{docker_devkit-0.2.1.dev37485576216 → docker_devkit-0.3.0}/tests/test_build_docker.py

@@ -3,13 +3,13 @@ from pathlib import Path
 from typing import Any
 
 import pytest
-import typer
 
 from docker_devkit import build_docker
 from docker_devkit.build_docker import DIGEST_FILE_NAME, distill_digest_manifest, push_image_digests
 
 DIGEST_A = "sha256:" + "a" * 64
 DIGEST_B = "sha256:" + "b" * 64
+BUILD_SHA = "c" * 40
 REPO_ZED = "ghcr.io/outernet-foundation/placeframe-capture-tool/zed-capture"
 REPO_AOA = "ghcr.io/outernet-foundation/placeframe-capture-tool/aoa-bridge"
 
@@ -45,9 +45,9 @@ def test_distills_single_target_single_tag() -> None:
 
 
 def test_distills_multiple_tags_from_comma_separated_refs() -> None:
-    baked = _baked("zed-capture", refs=f"{REPO_ZED}:tree-abc,{REPO_ZED}:run-42", digest=DIGEST_A)
+    baked = _baked("zed-capture", refs=f"{REPO_ZED}:tree-abc,{REPO_ZED}:latest", digest=DIGEST_A)
     assert distill_digest_manifest(baked, ["zed-capture"]) == {
-        "zed-capture": {"ref": REPO_ZED, "digest": DIGEST_A, "tags": ["tree-abc", "run-42"]}
+        "zed-capture": {"ref": REPO_ZED, "digest": DIGEST_A, "tags": ["tree-abc", "latest"]}
     }
 
 
@@ -69,31 +69,29 @@ def test_strips_digest_suffix_from_refs() -> None:
     assert entry["tags"] == ["tree-abc"]
 
 
-def test_push_image_digests_is_noop_without_builds_registry(monkeypatch: pytest.MonkeyPatch) -> None:
-    recorder = PushBuildRecorder()
-    monkeypatch.setattr(build_docker, "push_build", recorder)
-    baked = _baked("zed-capture", refs=f"{REPO_ZED}:tree-abc", digest=DIGEST_A)
-    push_image_digests(None, 42, baked, ["zed-capture"])
-    assert recorder.calls == []
-
-
-def test_push_image_digests_rejects_zero_run_number() -> None:
-    with pytest.raises(typer.BadParameter):
-        push_image_digests("ghcr.io/owner/builds", 0, {}, [])
+def test_refuses_target_with_no_tagged_references() -> None:
+    baked = _baked("zed-capture", refs=f"{REPO_ZED}@{DIGEST_A}", digest=DIGEST_A)
+    with pytest.raises(ValueError, match="zed-capture"):
+        distill_digest_manifest(baked, ["zed-capture"])
 
 
 def test_push_image_digests_pushes_manifest_to_images_digests_all(monkeypatch: pytest.MonkeyPatch) -> None:
     recorder = PushBuildRecorder()
     monkeypatch.setattr(build_docker, "push_build", recorder)
-    baked = _baked("zed-capture", refs=f"{REPO_ZED}:tree-abc,{REPO_ZED}:run-42", digest=DIGEST_A)
-    push_image_digests("ghcr.io/owner/builds", 42, baked, ["zed-capture"])
+    baked = _baked("zed-capture", refs=f"{REPO_ZED}:tree-abc,{REPO_ZED}:latest", digest=DIGEST_A)
+    push_image_digests("ghcr.io/owner/builds", BUILD_SHA, baked, ["zed-capture"])
     assert len(recorder.calls) == 1
     registry, project, platform, tag, _source_directory, paths = recorder.calls[0]
     assert registry == "ghcr.io/owner/builds"
     assert project == "images-digests"
     assert platform == "all"
-    assert tag == "run-42"
+    assert tag == f"sha-{BUILD_SHA}-{build_docker.leg_key(['zed-capture'])}"
     assert paths == [DIGEST_FILE_NAME]
     assert recorder.manifests == [
-        {"zed-capture": {"ref": REPO_ZED, "digest": DIGEST_A, "tags": ["tree-abc", "run-42"]}}
+        {"zed-capture": {"ref": REPO_ZED, "digest": DIGEST_A, "tags": ["tree-abc", "latest"]}}
     ]
+
+
+def test_leg_key_is_order_insensitive() -> None:
+    assert build_docker.leg_key(["zed-capture", "aoa-bridge"]) == build_docker.leg_key(["aoa-bridge", "zed-capture"])
+    assert build_docker.leg_key(["zed-capture"]) != build_docker.leg_key(["aoa-bridge"])