diff --git a/.github/workflows/update-gnome-extensions.yml b/.github/workflows/update-gnome-extensions.yml new file mode 100644 index 000000000..b53cd50e2 --- /dev/null +++ b/.github/workflows/update-gnome-extensions.yml @@ -0,0 +1,108 @@ +name: Update GNOME extensions + +on: + schedule: + - cron: "29 4 * * 1" + workflow_dispatch: + +permissions: {} + +concurrency: + group: utah-gnome-extension-update + cancel-in-progress: false + +jobs: + update: + runs-on: ubuntu-26.04 + permissions: + contents: write + pull-requests: write + actions: write + steps: + - name: Checkout + uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5 + with: + ref: main + persist-credentials: false + submodules: true + + - name: Bump extension submodules to tracked-branch heads + id: bump + run: | + set -euo pipefail + # create-pull-request runs even on an empty diff so a reversion can + # close the stale bump PR. It still needs a body file on that path. + : > "$RUNNER_TEMP/gnome-extensions-pr.md" + paths=$(git config --file .gitmodules --get-regexp '^submodule\..*\.path' | cut -d' ' -f2) + # Word-splitting intended: one path per line, no spaces in tree. + # shellcheck disable=SC2086 + echo "$paths" | xargs git submodule update --init --depth 1 -- + # A shallow submodule checkout fetches only the remote default + # branch. Fetch each configured branch explicitly before selecting + # it, since some extensions track a non-default release branch. + git config --file .gitmodules --get-regexp '^submodule\..*\.path$' | + while read -r key path; do + name=${key#submodule.} + name=${name%.path} + branch=$(git config --file .gitmodules --get "submodule.$name.branch" || true) + if [ -n "$branch" ]; then + git -C "$path" fetch --depth=1 origin \ + "+refs/heads/$branch:refs/remotes/origin/$branch" + git -C "$path" checkout --detach "refs/remotes/origin/$branch" + else + git submodule update --remote --depth 1 -- "$path" + fi + done + { + echo "# GNOME extension bumps" + echo + echo "Moves each extension submodule to the head of its tracked branch." + echo "This workflow dispatches contract-only CI on the proposed branch." + echo "It does not run the image-side extension verifier or build an image." + echo + echo "This PR intentionally does not auto-merge; a new upstream" + echo "head can break the GNOME 51 support range or the build" + echo "script's assumptions (paths, schemas, meson targets)." + echo + echo "## Heads" + echo + echo "| extension | old | new | GNOME shell-version |" + echo "|---|---|---|---|" + while read -r p; do + old=$(git ls-tree HEAD "$p" | cut -f1 | cut -d' ' -f3) + new=$(git -C "$p" rev-parse HEAD) + if [ "$old" = "$new" ]; then + ver="(unchanged)" + else + ver=$(python3 scripts/gnome-extension-shell-versions.py "$p") + fi + # shellcheck disable=SC2016 + printf '| `%s` | `%s` | `%s` | %s |\n' "$p" "${old:0:12}" "${new:0:12}" "$ver" + done <<< "$paths" + } > "$RUNNER_TEMP/gnome-extensions-pr.md" + # Always run create-pull-request, including on an empty diff, so it + # can close a stale automation PR after an upstream reversion. + + - name: Propose GNOME extension update + id: propose + uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8 + with: + branch: automation/gnome-extension-bumps + title: 'ci(extensions): bump pinned GNOME extensions' + commit-message: 'ci(extensions): bump pinned GNOME extensions' + body-path: ${{ runner.temp }}/gnome-extensions-pr.md + # One directory covers future extension additions; only gitlinks change. + add-paths: | + system_files/shared/usr/share/gnome-shell/extensions + + - name: Start the contract checks on the bump branch explicitly + if: contains(fromJSON('["created", "updated"]'), steps.propose.outputs.pull-request-operation) + env: + GH_TOKEN: ${{ github.token }} + REPOSITORY: ${{ github.repository }} + # contract_only: a dispatch is not a pull_request event, so a full + # build here would push and sign testing images from unreviewed + # upstream extension heads. Run the contract gates only. + run: | + gh workflow run build.yml --repo "$REPOSITORY" --ref automation/gnome-extension-bumps \ + -f contract_only=true diff --git a/.gitmodules b/.gitmodules index 309a37d0e..7a820bbb6 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,7 +1,7 @@ [submodule "system_files/shared/usr/share/gnome-shell/extensions/appindicatorsupport@rgcjonas.gmail.com"] path = system_files/shared/usr/share/gnome-shell/extensions/appindicatorsupport@rgcjonas.gmail.com url = https://github.com/ubuntu/gnome-shell-extension-appindicator.git - branch = v65 + branch = master [submodule "system_files/shared/usr/share/gnome-shell/extensions/tmp/bazaar-integration@kolunmi.github.io"] path = system_files/shared/usr/share/gnome-shell/extensions/tmp/bazaar-integration@kolunmi.github.io url = https://github.com/projectbluefin/bazaar-companion.git diff --git a/docs/skills/ci-workflows.md b/docs/skills/ci-workflows.md index cc2d37e54..6df2b071f 100644 --- a/docs/skills/ci-workflows.md +++ b/docs/skills/ci-workflows.md @@ -12,10 +12,9 @@ status: active dependencies: [] tags: [ci, workflows, actions, promotion] description: >- - build.yml contract gate, kernel-cache job, main/kernel matrix split, - promote-testing-to-main, sync-main-to-testing and update-bluefin-parity, - actions@v1 delegation, Renovate factory pin. Use when changing - .github/workflows/ or debugging a red run. + Build and contract jobs, promotion, branch sync, parity and extension + update workflows, reusable actions and Renovate pins. Use when editing + GitHub Actions or debugging CI. metadata: type: reference --- @@ -77,6 +76,18 @@ post-build verification workflows, not the complete workflow inventory: `created` or `updated` (not on the parity diff alone), so a nightly run against an unmerged, unchanged bump branch does not re-dispatch for nothing. +- `.github/workflows/update-gnome-extensions.yml` -- weekly and manual + submodule updates. Each `.gitmodules` branch must name a real remote branch; + `git submodule update --remote` cannot follow a tag written as a branch. + The generated report reads upstream metadata through + `scripts/gnome-extension-shell-versions.py`, which reuses the metadata + paths in `scripts/verify-gnome-extensions.py` (`SOURCE_EXTENSIONS`); update + that map when adding an extension. Paths are passed as argv and + shell-version values are allow-listed before entering the Markdown table. + Its dispatch uses `contract_only=true`, so it runs source contract checks + only: it does not build an image or run the image-side extension verifier. + A trusted full image build remains necessary before merge. No automated + merge is enabled. - `.github/workflows/post-testing-e2e.yml` -- successful non-PR testing builds explicitly dispatch this, or manually supply a successful testing build run ID. diff --git a/docs/skills/desktop-contract.md b/docs/skills/desktop-contract.md index ed135d8d6..d0a625903 100644 --- a/docs/skills/desktop-contract.md +++ b/docs/skills/desktop-contract.md @@ -1,7 +1,7 @@ --- name: desktop-contract version: "1.0" -last_updated: "2026-10-06" +last_updated: "2026-10-11" id: desktop-contract one_line_purpose: Maintain Utah identity, Bluefin desktop defaults, and first-boot Flatpak policy. entry_point: docs/skills/desktop-contract.md @@ -245,10 +245,11 @@ for the live image's own `installer-local` remote. ## GNOME extensions are pinned submodules Bluefin's GNOME extension submodules are retained with their normal build -step. `.gitmodules` pins eight of them by URL and branch under -`system_files/shared/usr/share/gnome-shell/extensions/` — appindicator, -bazaar-integration, blur-my-shell, caffeine, custom-command-list, -dash-to-dock, gradia-integration, and gsconnect. Search Light was dropped: +step. `.gitmodules` pins all 16 extension trees by URL and branch under +`system_files/shared/usr/share/gnome-shell/extensions/`. The weekly +`update-gnome-extensions.yml` workflow advances the configured branches and +opens a review PR; edit `.gitmodules` directly when changing a source or its +tracked branch. Search Light was dropped: its shader code calls `set_shader_source`, which GNOME 51 removed, so the extension errored at load and failed the ISO end-to-end test on every flavor. diff --git a/docs/skills/index.json b/docs/skills/index.json index 8081ffb4b..c0cab892f 100644 --- a/docs/skills/index.json +++ b/docs/skills/index.json @@ -14,7 +14,7 @@ "actions", "promotion" ], - "description": "build.yml contract gate, kernel-cache job, main/kernel matrix split, promote-testing-to-main, sync-main-to-testing and update-bluefin-parity, actions@v1 delegation, Renovate factory pin. Use when changing .github/workflows/ or debugging a red run.", + "description": "Build and contract jobs, promotion, branch sync, parity and extension update workflows, reusable actions and Renovate pins. Use when editing GitHub Actions or debugging CI.", "version": "1.1", "last_updated": "2026-10-11", "doc_type": "reference" @@ -52,7 +52,7 @@ ], "description": "The runtime desktop contract in contracts/bluefin-desktop.toml and its in-image verifiers. Use when changing branding, os-release, service presets, GNOME extensions, or first-boot Flatpak behavior.", "version": "1.0", - "last_updated": "2026-10-06", + "last_updated": "2026-10-11", "doc_type": "policy" }, { diff --git a/scripts/gnome-extension-shell-versions.py b/scripts/gnome-extension-shell-versions.py new file mode 100644 index 000000000..307c9d300 --- /dev/null +++ b/scripts/gnome-extension-shell-versions.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python3 +"""Print shell-version metadata safely for the GNOME extension bump report.""" + +from __future__ import annotations + +import importlib.util +import json +import re +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +EXTENSIONS_BASE = REPO_ROOT / "system_files/shared/usr/share/gnome-shell/extensions" + +# Reuse the verifier's metadata map so the report reads the same files the +# source contract checks (many extensions keep metadata under src/ etc.). +_SPEC = importlib.util.spec_from_file_location( + "verify_gnome_extensions", REPO_ROOT / "scripts/verify-gnome-extensions.py" +) +assert _SPEC is not None and _SPEC.loader is not None +_VERIFIER = importlib.util.module_from_spec(_SPEC) +_SPEC.loader.exec_module(_VERIFIER) +SOURCE_EXTENSIONS: dict[str, str] = _VERIFIER.SOURCE_EXTENSIONS + +FALLBACK_LOCATIONS = ("metadata.json", "data/metadata.json.in") + + +def metadata_files(extension: Path, base: Path = EXTENSIONS_BASE) -> list[tuple[str, Path]]: + """Return (uuid, metadata path) pairs for the extension submodule.""" + try: + submodule = extension.resolve().relative_to(base.resolve()) + except ValueError: + submodule = None + found = [] + if submodule is not None: + for uuid, relative in SOURCE_EXTENSIONS.items(): + rel = Path(relative) + if rel.parts[: len(submodule.parts)] == submodule.parts: + found.append((uuid, extension / rel.relative_to(submodule))) + if found: + return found + for location in FALLBACK_LOCATIONS: + if (extension / location).is_file(): + return [("", extension / location)] + return [] + + +def read_versions(metadata: Path) -> str: + try: + data = json.loads(metadata.read_text().replace("@PACKAGE_VERSION@", "0")) + except (OSError, json.JSONDecodeError): + return "?" + if not isinstance(data, dict): + return "?" + + versions = data.get("shell-version") + if not isinstance(versions, list) or not all( + isinstance(item, str) and re.fullmatch(r"\d+(?:\.\d+)*", item) + for item in versions + ): + return "?" + + # Shell API versions are numeric. Reject anything else because this value + # is rendered into a Markdown table in a write-enabled automation job. + return ", ".join(versions) or "?" + + +def shell_versions(extension: Path, base: Path = EXTENSIONS_BASE) -> str: + """Read the extension's metadata and escape values for a Markdown table.""" + files = metadata_files(extension, base) + if not files: + return "?" + if len(files) == 1: + return read_versions(files[0][1]) + # UUIDs come from the trusted in-repo map, not upstream content. + return "; ".join(f"{uuid}: {read_versions(path)}" for uuid, path in files) + + +def main() -> int: + if len(sys.argv) != 2: + print("usage: gnome-extension-shell-versions.py EXTENSION_PATH", file=sys.stderr) + return 2 + print(shell_versions(Path(sys.argv[1]))) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_gnome_extension_shell_versions.py b/tests/test_gnome_extension_shell_versions.py new file mode 100644 index 000000000..99bfd4018 --- /dev/null +++ b/tests/test_gnome_extension_shell_versions.py @@ -0,0 +1,84 @@ +from __future__ import annotations + +import importlib.util +import tempfile +import unittest +from pathlib import Path + +SCRIPT = Path(__file__).resolve().parents[1] / "scripts/gnome-extension-shell-versions.py" +SPEC = importlib.util.spec_from_file_location("gnome_extension_shell_versions", SCRIPT) +assert SPEC is not None and SPEC.loader is not None +MODULE = importlib.util.module_from_spec(SPEC) +SPEC.loader.exec_module(MODULE) + + +class ShellVersionReportTests(unittest.TestCase): + def test_reads_shell_versions_from_root_metadata(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + extension = Path(tmp) / "extension'`" + extension.mkdir() + (extension / "metadata.json").write_text('{"shell-version": ["50", "51"]}') + self.assertEqual(MODULE.shell_versions(extension), "50, 51") + + def test_reads_gsconnect_template_location(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + extension = Path(tmp) / "extension'`" + metadata_dir = extension / "data" + metadata_dir.mkdir(parents=True) + (metadata_dir / "metadata.json.in").write_text( + '{"version": "@PACKAGE_VERSION@", "shell-version": ["51"]}' + ) + self.assertEqual(MODULE.shell_versions(extension), "51") + + def test_uses_verifier_metadata_location_for_nested_sources(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + base = Path(tmp) + extension = base / "tmp/tilingshell@ferrarodomenico.com" + (extension / "resources").mkdir(parents=True) + (extension / "resources/metadata.json").write_text('{"shell-version": ["51"]}') + self.assertEqual(MODULE.shell_versions(extension, base), "51") + + def test_reports_each_extension_in_multi_extension_submodule(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + base = Path(tmp) + extension = base / "tmp/bluefin-bling" + for name, version in (("syncthing-toggle", "50"), ("power-status-color", "51")): + (extension / "extensions" / name).mkdir(parents=True) + (extension / "extensions" / name / "metadata.json").write_text( + '{"shell-version": ["%s"]}' % version + ) + self.assertEqual( + MODULE.shell_versions(extension, base), + "syncthing-toggle@projectbluefin.io: 50; power-status-color@projectbluefin.io: 51", + ) + + def test_every_submodule_maps_to_verifier_metadata(self) -> None: + import subprocess + + paths = subprocess.run( + ["git", "config", "--file", ".gitmodules", "--get-regexp", r"^submodule\..*\.path$"], + cwd=MODULE.REPO_ROOT, capture_output=True, text=True, check=True, + ).stdout.split()[1::2] + for path in paths: + with self.subTest(path=path): + files = MODULE.metadata_files(MODULE.REPO_ROOT / path) + self.assertTrue(files and all(uuid for uuid, _ in files)) + + def test_rejects_untrusted_metadata_for_markdown_table(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + extension = Path(tmp) + (extension / "metadata.json").write_text( + '{"shell-version": ["51|oops", "52`\\nrow"]}' + ) + self.assertEqual(MODULE.shell_versions(extension), "?") + + def test_missing_or_invalid_metadata_is_unknown(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + extension = Path(tmp) + self.assertEqual(MODULE.shell_versions(extension), "?") + (extension / "metadata.json").write_text("not json") + self.assertEqual(MODULE.shell_versions(extension), "?") + + +if __name__ == "__main__": + unittest.main()