Regenerate the widget gallery on pushes to main

[matt-edmondson]

Requested by Matt · project thread

Before: docs/gallery/ changed only when someone ran tools/WidgetGallery by hand and committed the output. On main today it is behind: five widgets have no tile yet, and the Material Icons tiles show placeholder boxes.

After: every push to main that touches a project the gallery builds from reruns the tool. When the pictures changed, the workflow commits docs/gallery/ back to main as [bot][skip ci] Regenerate the widget gallery. When they didn't change, it commits nothing.

The new workflow is .github/workflows/widget-gallery.yml. It reuses the existing tool rather than adding a generator.

Why it can't loop or cut a release

• It pushes with GITHUB_TOKEN. GitHub starts no workflow run for a push made with that token, so neither this workflow nor ci.yml fires on the bot's commit.
• The message carries [bot][skip ci]. That is the prefix KtsuBuild's own metadata commits use. KtsuBuild leaves those commits out of versioning and the changelog, and GitHub skips push workflows for them even if the token ever changes.
• The commit only touches docs/gallery/, which is outside the workflow's paths: filter.

Why no token or ruleset change is needed

The main ruleset in infrastructure/github/rulesets.tf already lists github-actions[bot] (actor 15368) as an always-bypass actor. That is the identity behind GITHUB_TOKEN, and it is how KtsuBuild pushes its metadata commits today. Nothing changes in ktsu-dev/infrastructure.

How

• Checkout. LFS content is not downloaded. git lfs install --local makes the new PNGs commit as LFS pointers, and a guard fails the job if any image is staged as a raw blob.
• Icon font. Material Icons is downloaded from google/material-design-icons, pinned to a commit and checked against a SHA-256, so the date picker, file tree and dialog tiles render real glyphs.
• Cleanup and staging. Old images are deleted before regenerating, so a renamed or removed tile goes with it. Only docs/gallery is staged; the build also rewrites .gitignore, and that change is discarded.
• Push race. The release job pushes its own metadata commit from the same main push. When that lands first, the gallery commit rebases and retries, up to five times.
• Concurrency. A newer push cancels an older gallery run still in progress.

Tested locally against a bare remote

• First run: 16 changed images committed as LFS pointers, with their objects uploaded.
• Push race: a metadata commit pushed first made the push reject. The workflow rebased and pushed on the second attempt. The first version failed here, because the rebase refused to run over the build's .gitignore rewrite; that is fixed.
• No-op rerun: "The widget gallery is up to date." and no commit.
• Determinism: two renders on Linux were byte-identical.

Things to know

• The first run after merge will commit about 16 images, catching main up.
• The file dialog and file tree tiles show the runner's mounts. A GitHub runner image update could occasionally move a pixel there and cause a gallery commit.
• Docs: a short note in the CI/CD section of CLAUDE.md and a "Regenerated on main" section in tools/WidgetGallery/README.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UAiQ9k8PXay5udWkN4vi3U

---

Generated by Claude Code