Symptom to cause to fix for build, CI, and runtime failures, plus the pre-commit checklist. Use when something is broken or before opening a pull request.
The English summary is being prepared. Showing the original description.
Run score Not tested
See how to installReview the instructions the agent will receive before you install.
just lint — shellcheck on every tracked script.just check — Justfile syntax.just test-unit — the suite.just validate-brewfiles / just validate-flatpaks if those changed.just build if the image changed.CI runs the same checks; running them locally only makes the pull request quiet.
| Symptom | Cause | Fix |
|---|---|---|
bootc container lint fails on a nonempty /run | a script wrote to /run into an image layer | remove it in 90-cleanup.sh; that phase deliberately does not mount /run as tmpfs |
| a third-party repository is live in the final image | a script enabled it and did not disable it | use copr_install_isolated, or disable it explicitly |
| the package layer rebuilds on every overlay edit | packages drifted into the overlay phase | keep packages in 20-packages-and-services.sh |
| hadolint flags the Containerfile | a rule in .github/hadolint.yaml | fix it, or add a suppression with a reason |
| Symptom | Cause | Fix |
|---|---|---|
validate never runs | branch protection names a check no workflow produces | the context must be exactly validate |
| Renovate logs a skip and opens nothing | RENOVATE_TOKEN is not set | expected; set the secret to turn Renovate on |
Renovate fails on Validate RENOVATE_TOKEN | the token is expired or lacks the workflow scope | recreate the token |
| the promotion PR never opens | stable does not exist | create the branch |
| the promotion PR will not merge | stable requires an approval | set required approvals to 0 |
| a Renovate PR waits forever | auto-merge is off | enable it in Settings |
The two most common first-boot surprises — no Flatpaks, and no brew — are in
the README's Troubleshooting section.
| Symptom | Cause | Fix |
|---|---|---|
ujust shows no custom commands | 60-custom.just was not written or imported | check that 10-overlay.sh copied the recipes |
When a fix here was non-obvious, put it in the skill that owns the area, in the same pull request. That is the only home for durable learning.
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
GitHub Actions, Renovate, the two-branch release model, signing, and promotion. Use when changing workflows, dependency policy, or releasing.
The English summary is being prepared. Showing the original description.
Decide where a package, app, or command belongs — dnf5 at build time, Homebrew, Flatpak, or ujust — and how each is validated. Use when adding or removing something from the image.
The English summary is being prepared. Showing the original description.
Bootstrap a new image from this template: rename the project, enable Actions and Renovate, protect the branch, and reach a first green build. Use when forking the template or when setup has stalled.
The English summary is being prepared. Showing the original description.
Architecture, repository layout, and file map for this template. Use when orienting to the repository, tracing how the image is assembled, or deciding which skill covers a task.
The English summary is being prepared. Showing the original description.