docker-devkit 0.2.1.dev37490360141__tar.gz → 0.3.0.dev113__tar.gz

{docker_devkit-0.2.1.dev37490360141 → docker_devkit-0.3.0.dev113}/.github/actions/setup-release-devkit/action.yml

@@ -5,7 +5,7 @@ runs:
   steps:
     - shell: bash
       env:
-        RELEASE_DEVKIT_COMMIT: ed406a0d88445dd601b7cbe47decbb6371694e3a
+        RELEASE_DEVKIT_COMMIT: 84afa7a39ba21ab8971014dbefe130e3b9df8ded
       run: |
         git clone https://github.com/outernet-foundation/release-devkit.git "$RUNNER_TEMP/release-devkit"
         git -C "$RUNNER_TEMP/release-devkit" checkout "$RELEASE_DEVKIT_COMMIT"

{docker_devkit-0.2.1.dev37490360141 → docker_devkit-0.3.0.dev113}/.github/workflows/integrate.yml

@@ -54,3 +54,24 @@ jobs:
       - *uv-restore
       - *setup-release-devkit
       - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev validate-release-plan
+
+  update-pr-draft-release:
+    if: github.event.pull_request
+    needs: [validate-release-plan]
+    permissions:
+      contents: write
+      packages: read
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          # Perform a full clone, required for tags
+          fetch-depth: 0
+          fetch-tags: true
+          persist-credentials: false
+      - *uv-restore
+      - *setup-release-devkit
+      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev release --channel pr
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

{docker_devkit-0.2.1.dev37490360141 → docker_devkit-0.3.0.dev113}/.github/workflows/merge-gate.yml

@@ -22,7 +22,7 @@ jobs:
       - uses: actions/checkout@v5
         with:
           ref: ${{ github.event.pull_request.head.sha || github.event.workflow_run.head_sha }}
-          # Perform a full clone, required so merge-gate can validate that this PR is a fast forward from dev
+          # Perform a full clone, required so merge-gate can validate that this PR is a semi-linear merge into dev
           fetch-depth: 0
           persist-credentials: false
       - uses: astral-sh/setup-uv@v7
@@ -35,7 +35,6 @@ jobs:
         with:
           app-id: ${{ vars.MERGE_BOT_APP_ID }}
           private-key: ${{ secrets.MERGE_BOT_APP_PRIVATE_KEY }}
-      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev merge-gate
+      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev merge-gate --head-sha ${{ github.event.pull_request.head.sha || github.event.workflow_run.head_sha }}
         env:
           GITHUB_TOKEN: ${{ steps.mint.outputs.token }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha || github.event.workflow_run.head_sha }}

{docker_devkit-0.2.1.dev37490360141 → docker_devkit-0.3.0.dev113}/.github/workflows/release.yml

@@ -18,7 +18,6 @@ jobs:
       contents: write
       id-token: write
       packages: read
-      actions: read
     steps:
       - uses: actions/checkout@v5
         with:
@@ -33,7 +32,7 @@ jobs:
           save-cache: "false"
       - &setup-release-devkit
         uses: ./.github/actions/setup-release-devkit
-      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev prerelease
+      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev release --channel dev
         env:
           GITHUB_TOKEN: ${{ github.token }}
 
@@ -53,6 +52,6 @@ jobs:
           persist-credentials: true
       - *uv-restore
       - *setup-release-devkit
-      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev release
+      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev release --channel stable
         env:
           GITHUB_TOKEN: ${{ github.token }}

{docker_devkit-0.2.1.dev37490360141 → docker_devkit-0.3.0.dev113}/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 three-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.dev37490360141 → docker_devkit-0.3.0.dev113}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: docker-devkit
-Version: 0.2.1.dev37490360141
+Version: 0.3.0.dev113
 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.dev37490360141 → docker_devkit-0.3.0.dev113}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "docker-devkit"
-version = "0.2.1.dev37490360141"
+version = "0.3.0.dev113"
 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.dev113/release-devkit.yaml

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

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

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import platform
@@ -7,12 +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 ci_devkit.setup_oras import install_oras
+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
@@ -32,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"
@@ -50,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)
@@ -113,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
@@ -176,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(
@@ -187,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"
@@ -201,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:
@@ -230,29 +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],
         )
@@ -273,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.dev37490360141 → docker_devkit-0.3.0.dev113}/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.dev37490360141 → docker_devkit-0.3.0.dev113}/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"])

{docker_devkit-0.2.1.dev37490360141 → docker_devkit-0.3.0.dev113}/tests/test_matrix.py

@@ -7,12 +7,20 @@ from docker_devkit.documents import BakeDocument
 from docker_devkit.matrix import compute_matrix_entries
 
 
-def service(dockerfile: str, *, tags: bool = True, contexts: dict[str, str] | None = None) -> dict[str, object]:
+def service(
+    dockerfile: str,
+    *,
+    tags: bool = True,
+    contexts: dict[str, str] | None = None,
+    platforms: list[str] | None = None,
+) -> dict[str, object]:
     build: dict[str, object] = {"dockerfile": dockerfile}
     if tags:
         build["tags"] = [f"registry/{dockerfile}:latest"]
     if contexts is not None:
         build["additional_contexts"] = contexts
+    if platforms is not None:
+        build["platforms"] = platforms
     return {"build": build}
 
 
@@ -65,16 +73,59 @@ def test_single_service_repo_emits_matrix_of_one() -> None:
     assert compute_matrix_entries(bake) == [{"targets": "livekit-token", "variant": "common"}]
 
 
-def test_cross_compile_targets_are_excluded() -> None:
+def test_cross_compile_targets_get_their_own_legs() -> None:
     bake = BakeDocument.model_validate({
         "services": {
             "api": service("docker/api/Dockerfile"),
+            "postgres": service("docker/postgres/Dockerfile"),
             "zed-capture": service("docker/zed-capture/Dockerfile"),
         },
         "x-cross-compile-targets": ["zed-capture"],
     })
 
-    assert compute_matrix_entries(bake) == [{"targets": "api", "variant": "common"}]
+    assert compute_matrix_entries(bake) == [
+        {"targets": "api postgres", "variant": "common"},
+        {"targets": "zed-capture", "variant": "common"},
+    ]
+
+
+def test_platform_pinned_services_join_the_cross_compile_cohort() -> None:
+    bake = BakeDocument.model_validate({
+        "services": {
+            "api": service("docker/api/Dockerfile"),
+            "zed-capture": service("docker/zed-capture/Dockerfile", platforms=["linux/arm64"]),
+            "aoa-bridge": service("docker/aoa-bridge/Dockerfile", platforms=["linux/arm64"]),
+        }
+    })
+
+    assert compute_matrix_entries(bake) == [
+        {"targets": "api", "variant": "common"},
+        {"targets": "aoa-bridge zed-capture", "variant": "common"},
+    ]
+
+
+def test_unknown_cross_compile_target_fails_loudly() -> None:
+    bake = BakeDocument.model_validate({
+        "services": {"api": service("docker/api/Dockerfile")},
+        "x-cross-compile-targets": ["missing"],
+    })
+
+    with pytest.raises(RuntimeError, match="unknown services"):
+        compute_matrix_entries(bake)
+
+
+def test_group_spanning_cohort_membership_fails_loudly() -> None:
+    bake = BakeDocument.model_validate({
+        "services": {
+            "api": service("docker/api/Dockerfile"),
+            "zed-capture": service(
+                "docker/zed-capture/Dockerfile", contexts={"api": "target:api"}, platforms=["linux/arm64"]
+            ),
+        }
+    })
+
+    with pytest.raises(RuntimeError, match="spans cross-compile cohort"):
+        compute_matrix_entries(bake)
 
 
 def test_non_target_additional_contexts_do_not_group() -> None:
@@ -111,7 +162,7 @@ def test_unknown_target_reference_fails_loudly() -> None:
         compute_matrix_entries(bake)
 
 
-def test_matrix_main_prints_github_output_line(
+def test_matrix_main_prints_bare_leg_list(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
     (tmp_path / "workloads").mkdir()
@@ -125,5 +176,5 @@ def test_matrix_main_prints_github_output_line(
 
     matrix_main()
 
-    payload = json.loads(capsys.readouterr().out.splitlines()[0][len("matrix=") :])
-    assert payload == {"include": [{"targets": "livekit-token", "variant": "common"}]}
+    payload = json.loads(capsys.readouterr().out)
+    assert payload == [{"targets": "livekit-token", "variant": "common"}]

{docker_devkit-0.2.1.dev37490360141 → docker_devkit-0.3.0.dev113}/uv.lock

@@ -42,17 +42,17 @@ wheels = [
 ]
 
 [[package]]
-name = "ci-devkit"
-version = "0.2.0"
+name = "build-artifact-registry"
+version = "0.2.0.dev38101394871"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "bashrun" },
     { name = "pydantic" },
     { name = "pydantic-settings" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/fd/c6/94c2a4a406b593ca3a1140151c0cb2c1367b30bf295f32a4bf9c92c100ac/ci_devkit-0.2.0.tar.gz", hash = "sha256:a16e0a91771a5b50205646577e8d56198c7c3262a063d7ebcf9a82fc26a2e3e0", size = 53288, upload-time = "2026-10-05T15:02:35.926Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/d2/35/7bd270fb56bbbcee40ee2f3834b07e912fb69ff62f84560f7a2e08a3759a/build_artifact_registry-0.2.0.dev38101394871.tar.gz", hash = "sha256:d19575c8315f808cbd5d6e6011dbe2eb03a2b1bc25865482ddbf14acccb1dace", size = 36173, upload-time = "2026-10-11T01:21:07.61Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ce/d7/f7b91b7e62ed5cd7864f4ddbf84851ad5a31938342cb00e28bf15a7064c2/ci_devkit-0.2.0-py3-none-any.whl", hash = "sha256:d86403effbe36563b0a471d860e5e1e46ae7793d7d203a2dcc5561e91d1163f6", size = 28022, upload-time = "2026-10-05T15:02:34.654Z" },
+    { url = "https://files.pythonhosted.org/packages/41/e4/4cb0cc61d42f3822aec3f66b27490e3dfa44ecc26109093236c868528121/build_artifact_registry-0.2.0.dev38101394871-py3-none-any.whl", hash = "sha256:b124930a6b565ce0861d3bc6f680cbca92bf81334caef077b5b00666cee9257f", size = 10745, upload-time = "2026-10-11T01:21:06.485Z" },
 ]
 
 [[package]]
@@ -70,7 +70,7 @@ version = "0.0.0.dev0"
 source = { editable = "." }
 dependencies = [
     { name = "bashrun" },
-    { name = "ci-devkit" },
+    { name = "build-artifact-registry" },
     { name = "packaging" },
     { name = "pathspec" },
     { name = "pydantic" },
@@ -93,7 +93,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "bashrun", specifier = ">=0.1.0" },
-    { name = "ci-devkit", specifier = ">=0.1.15" },
+    { name = "build-artifact-registry", specifier = ">=0.2.0.dev0" },
     { name = "packaging", specifier = ">=24.1" },
     { name = "pathspec", specifier = ">=1.0.4" },
     { name = "pydantic", specifier = ">=2.11.7" },
@@ -107,7 +107,7 @@ requires-dist = [
 dev = [
     { name = "basedpyright", specifier = ">=1.39.10" },
     { name = "pytest", specifier = ">=8.0.0" },
-    { name = "python-devkit", specifier = ">=0.1.0" },
+    { name = "python-devkit", specifier = ">=0.3.0.dev0" },
     { name = "ruff", specifier = ">=0.14.11" },
     { name = "types-pyyaml", specifier = ">=6.0.12.20260906" },
     { name = "types-strictyaml", specifier = ">=1.7.3.3" },
@@ -310,17 +310,16 @@ wheels = [
 
 [[package]]
 name = "python-devkit"
-version = "0.1.15"
+version = "0.3.0.dev38096025533"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "bashrun" },
-    { name = "ci-devkit" },
     { name = "pydantic" },
     { name = "typer" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/82/53/c3b37f69c35475b09cdf1c18deb193238d7ab5143ee6bc97e5c22c48fe87/python_devkit-0.1.15.tar.gz", hash = "sha256:ac1ef0f2a4622e9c97763f4e353005c41164e2d6d4b130cdb709e811947f253d", size = 34651, upload-time = "2026-09-30T04:12:18.88Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/85/07/160d8d87f184c1f9a32e2dd64a413695d10dad275d1684f89728d28c543c/python_devkit-0.3.0.dev38096025533.tar.gz", hash = "sha256:94b6f3d63b9192ede7d4bff2a3fabcc714a202807e2a7468c0047920837bb657", size = 33112, upload-time = "2026-10-10T23:47:13.476Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b6/81/da4f76cbfccb5a4d5a58a9f51d3e2b7d40f6dc9edd931d7891b2789adeae/python_devkit-0.1.15-py3-none-any.whl", hash = "sha256:0c13684cc780e3ba9b3e25feed61065b355e8fc7436bee043e7c6adf71fa40e7", size = 14537, upload-time = "2026-09-30T04:12:17.918Z" },
+    { url = "https://files.pythonhosted.org/packages/12/66/c87d7ab58ba1ded58dfb21fe0c9783231d7a67514fd335239bd95df58414/python_devkit-0.3.0.dev38096025533-py3-none-any.whl", hash = "sha256:605aeabb81770f6393e771518639512fd6a7c39b5a22554dfe747fd9de3a0205", size = 14633, upload-time = "2026-10-10T23:47:12.49Z" },
 ]
 
 [[package]]

docker_devkit-0.2.1.dev37490360141/release-devkit.yaml

@@ -1,7 +0,0 @@
-ci_workflow: release.yml
-packages:
-  docker-devkit:
-    path: .
-    major_minor: "0.2"
-    registries:
-      pypi: docker-devkit