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
108 changes: 108 additions & 0 deletions .github/workflows/update-gnome-extensions.yml
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion .gitmodules
Original file line number Diff line number Diff line change
@@ -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
Expand Down
19 changes: 15 additions & 4 deletions docs/skills/ci-workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
---
Expand Down Expand Up @@ -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.

Expand Down
11 changes: 6 additions & 5 deletions docs/skills/desktop-contract.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions docs/skills/index.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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"
},
{
Expand Down
88 changes: 88 additions & 0 deletions scripts/gnome-extension-shell-versions.py
Original file line number Diff line number Diff line change
@@ -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())
84 changes: 84 additions & 0 deletions tests/test_gnome_extension_shell_versions.py
Original file line number Diff line number Diff line change
@@ -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()
Loading