Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,9 @@ checks (`scripts/check-skill-frontmatter.sh`, `scripts/check-skill-index.sh`,
tracking issue. A missing contract package is a build failure, never a
silent skip.
- **`config/flavors.json` is the single source of the flavor set.** No
workflow may name `utah-nvidia` or `utah-gaming` literally — `just check`
fails on it. Retire a flavor by moving it under `retired` with the reason.
workflow or Justfile recipe may name `utah-nvidia` or `utah-gaming`
literally — `just check` fails on it. Retire a flavor by moving it under
`retired` with the reason.
- **Containerfile ARG digests are Renovate-managed pins** (`BASE_IMAGE`,
`PACKAGE_IMAGE_SHA`, `COMMON_IMAGE_SHA`, `BREW_IMAGE_SHA`). Do not bump them
by hand unless the task is exactly that. `Containerfile` and
Expand Down
33 changes: 12 additions & 21 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -110,13 +110,18 @@ check:
bash scripts/check-skill-frontmatter.sh
bash scripts/check-skill-index.sh
python3 scripts/generate_skill_index.py --check
# No workflow may carry its own copy of the flavor list. That drift is what
# config/flavors.json exists to stop: narrowing the build matrix while
# Neither workflows nor the Justfile may carry their own copy of the flavor
# list or flavored image names. That drift is what config/flavors.json and
# scripts/flavors.py exist to stop: narrowing the build matrix while
# promote and release still name images nothing produces fails late.
if grep -rn 'utah-nvidia\|utah-gaming' .github/workflows/; then
if grep -rnE 'utah-(nvidia|gaming)' .github/workflows/; then
echo 'no workflow may name a flavored image; read it from config/flavors.json' >&2
exit 1
fi
if grep -nE '(utah|\{\{ image \}\})-(nvidia|gaming)' Justfile; then
echo 'no recipe may name a flavored image; use flavors.py image' >&2
exit 1
fi

# Verify branding, desktop defaults, first-boot Flatpak policy, and service
# enablement in an already-composed image. The same verifier runs in the
Expand Down Expand Up @@ -154,15 +159,7 @@ check-parity:
fi

image_name base_name stream flavor:
#!/usr/bin/env bash
set -euo pipefail
case "{{ flavor }}" in
main) echo "{{ image }}" ;;
nvidia) echo "{{ image }}-nvidia" ;;
gaming) echo "{{ image }}-gaming" ;;
nvidia-gaming) echo "{{ image }}-nvidia-gaming" ;;
*) echo "unknown Utah image flavor: {{ flavor }}" >&2; exit 2 ;;
esac
@python3 scripts/flavors.py image "{{ flavor }}"

generate-default-tag stream build_number:
@echo "{{ stream }}"
Expand Down Expand Up @@ -190,13 +187,7 @@ build-ghcr base_name stream flavor kernel_pin="":
#!/usr/bin/env bash
set -euo pipefail
version="{{ stream }}-$(date -u +%Y%m%d)-$(git rev-parse --short HEAD)"
case "{{ flavor }}" in
main) image_name="{{ image }}" ;;
nvidia) image_name="{{ image }}-nvidia" ;;
gaming) image_name="{{ image }}-gaming" ;;
nvidia-gaming) image_name="{{ image }}-nvidia-gaming" ;;
*) echo "unknown Utah image flavor: {{ flavor }}" >&2; exit 2 ;;
esac
image_name="$(python3 scripts/flavors.py image '{{ flavor }}')"
# The kernel cache image and the layer cache below are both published
# private by default, and the reusable build workflow only logs in to GHCR
# for non-PR events -- so pulling either would 401 on exactly the runs that
Expand Down Expand Up @@ -302,7 +293,7 @@ tag-images image_name default_tag alias_tags:
gen-sbom base_name stream flavor syft_cmd:
#!/usr/bin/env bash
set -euo pipefail
image_name="$(just image_name '{{ base_name }}' '{{ stream }}' '{{ flavor }}')"
image_name="$(python3 scripts/flavors.py image '{{ flavor }}')"
mkdir -p "sbom_out/$image_name"
"{{ syft_cmd }}" "localhost/$image_name:{{ stream }}" -o json >"sbom_out/$image_name/sbom.json"

Expand Down Expand Up @@ -443,7 +434,7 @@ boot-vm:
secureboot base_name default_tag flavor:
#!/usr/bin/env bash
set -euo pipefail
image_name="$(just image_name '{{ base_name }}' '{{ default_tag }}' '{{ flavor }}')"
image_name="$(python3 scripts/flavors.py image '{{ flavor }}')"
podman run --rm --entrypoint /bin/sh "localhost/$image_name:{{ default_tag }}" -c 'test -e /usr/lib/modules || test -e /boot'

# Regenerate the status page's package data from the manifests. Run this after
Expand Down
27 changes: 17 additions & 10 deletions docs/skills/flavors.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: flavors
version: "1.0"
last_updated: "2026-09-05"
last_updated: "2026-09-18"
id: flavors
one_line_purpose: Add, remove, or retire an image flavor safely.
entry_point: docs/skills/flavors.md
Expand Down Expand Up @@ -29,6 +29,7 @@ kernel cache image is built at all.

```bash
python3 scripts/flavors.py list # ["main", "nvidia", "gaming", "nvidia-gaming"]
python3 scripts/flavors.py image nvidia # utah-nvidia
python3 scripts/flavors.py needs-kernel # true
```

Expand All @@ -41,16 +42,19 @@ stages, and the cache image all stay put either way. `retired` is not
commentary -- it is what a flavor moves to when it is switched off
(docstring, `scripts/flavors.py`).

## No workflow literals
## No workflow or Justfile literals

`just check` fails if any workflow names `utah-nvidia` or `utah-gaming`
directly (`Justfile`, `check` recipe; the guard is
`! grep -rn 'utah-nvidia\|utah-gaming' .github/workflows/`). No workflow may
carry its own copy of the flavor list -- that drift is what
`config/flavors.json` exists to stop. The literals were previously duplicated
across three workflows, so narrowing the build matrix while promote and
release still named images nothing produces failed late (recipe comment,
`Justfile`, `check`).
`just check` fails if any workflow or Justfile recipe names `utah-nvidia` or
`utah-gaming` directly (`Justfile`, `check` recipe; the guards are
`! grep -rnE 'utah-(nvidia|gaming)' .github/workflows/` and
`! grep -nE '(utah|\{\{ image \}\})-(nvidia|gaming)' Justfile`). No workflow
or recipe may carry its own copy of the flavor list or image names -- that drift
is what `config/flavors.json` and `scripts/flavors.py` exist to stop. Recipes
that need an image name ask for it at the source -- `build-ghcr`, `gen-sbom`,
and `secureboot` each run `python3 scripts/flavors.py image <flavor>` -- so
build, promote, and release always agree on published image names. `just
image_name` is the same query wrapped for callers outside the Justfile; no
recipe goes through it.

## The matrix is split in two, by what each flavor builds on

Expand All @@ -76,6 +80,9 @@ group on that name; Utah's Justfile ignores it when naming images.
building the cache is 45 minutes spent on nothing.
- `images` / `releases` -- the same set shaped for the promote and release
matrices (docstring, `scripts/flavors.py`).
- `image FLAVOR` -- the published image name for a flavor (e.g. `utah` or
`utah-nvidia`), called directly by the recipes that build, tag, or publish
images, and exposed to outside callers as `just image_name`.

Unknown names in `flavors` are a hard error at read time, so a typo in the
config fails before any matrix is built from it.
Expand Down
2 changes: 1 addition & 1 deletion docs/skills/index.json
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@
],
"description": "config/flavors.json is the single source for build, promote, and release matrices. Use when changing the flavor set or debugging a matrix that names an image nothing builds.",
"version": "1.0",
"last_updated": "2026-09-05",
"last_updated": "2026-09-18",
"doc_type": "procedure"
},
{
Expand Down
8 changes: 8 additions & 0 deletions scripts/flavors.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
flavors.py needs-kernel true / false
flavors.py list-main ["main"] flavors that build on the pristine base
flavors.py list-kernel ["nvidia", ...] flavors that build on the kernel cache
flavors.py image FLAVOR utah / utah-nvidia published image name for flavor
"""
import json
import sys
Expand Down Expand Up @@ -54,5 +55,12 @@
print(json.dumps([f for f in flavors if f == "main"]))
elif what == "list-kernel":
print(json.dumps([f for f in flavors if f != "main"]))
elif what == "image":
if len(sys.argv) < 3:
raise SystemExit("usage: flavors.py image FLAVOR")
flavor = sys.argv[2]
if flavor not in IMAGE:
raise SystemExit(f"unknown flavor: {flavor}")
print(IMAGE[flavor])
else:
raise SystemExit(f"unknown query: {what}")
32 changes: 30 additions & 2 deletions tests/test_flavors.py
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,30 @@ def test_images_maps_every_flavor_to_its_image_name(self):
{"image": "utah-nvidia-gaming"},
])

def test_image_maps_every_flavor_to_its_image_name(self):
cli = build_tree({"flavors": ALL_FLAVORS, "retired": {}})
for flavor, expected in (
("main", "utah"),
("nvidia", "utah-nvidia"),
("gaming", "utah-gaming"),
("nvidia-gaming", "utah-nvidia-gaming"),
):
result = run(cli, "image", flavor)
self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(result.stdout.strip(), expected)

def test_image_fails_without_flavor_argument(self):
cli = build_tree({"flavors": ALL_FLAVORS, "retired": {}})
result = run(cli, "image")
self.assertNotEqual(result.returncode, 0)
self.assertIn("usage: flavors.py image FLAVOR", result.stderr)

def test_image_fails_for_unknown_flavor(self):
cli = build_tree({"flavors": ALL_FLAVORS, "retired": {}})
result = run(cli, "image", "unknown-flavor")
self.assertNotEqual(result.returncode, 0)
self.assertIn("unknown flavor: unknown-flavor", result.stderr)

def test_releases_promotes_testing_to_stable_for_every_flavor(self):
cli = build_tree({"flavors": ["main", "gaming"], "retired": {}})
result = run(cli, "releases")
Expand Down Expand Up @@ -107,7 +131,7 @@ def test_list_main_is_empty_when_main_is_retired(self):

def test_unknown_flavor_in_config_fails_every_query(self):
cli = build_tree({"flavors": ["main", "utah-nvidia"], "retired": {}})
for query in ("list", "images", "releases", "needs-kernel", "list-kernel"):
for query in ("list", "images", "releases", "needs-kernel", "list-kernel", "image"):
result = run(cli, query)
self.assertNotEqual(result.returncode, 0, f"{query} accepted it")
self.assertIn("unknown flavor", result.stderr)
Expand Down Expand Up @@ -149,7 +173,11 @@ def test_shipped_config_agrees_across_all_queries(self):
run(SCRIPT, "needs-kernel").stdout.strip(),
"true" if kernel else "false",
)
self.assertEqual(
[run(SCRIPT, "image", f).stdout.strip() for f in flavors],
[i["image"] for i in images],
)


if __name__ == "__main__":
unittest.main()
unittest.main()
Loading