| name | finpilot-maintain |
| description | Maintenance of an active finpilot fork: Renovate digest PRs, README raptor section updates, signing verification, local test loops, and maintenance schedules. Use when maintaining a fork after onboarding. |
finpilot Maintenance
When to Use
- Reviewing and merging Renovate PRs for OCI digest bumps
- Updating the README "What Makes this Raptor Different" section after changes
- Verifying image signing works for production
- Running local test builds before pushing changes
- Planning a maintenance schedule for your fork
When NOT to Use
- First-time fork setup — use
finpilot-onboarding
- Adding new packages for the first time — use
finpilot-packages
- Debugging a specific build failure — use
finpilot-troubleshooting
Core Process
- Review incoming Renovate PRs — merge if CI passes
- Update README raptor section whenever packages or configuration change
- Run local test loop before opening PRs
- Open PRs to
main — never push directly
- Verify signing works after the first signed build
Handle Renovate Digest PRs
Renovate automatically opens PRs for:
- OCI image digest bumps in
Containerfile
- GitHub Actions SHA updates in workflows
- Pinned tool version updates (with
# renovate: datasource=... comments)
Review Checklist
Merge Strategy
Digest-only PRs are safe to automerge (configured in renovate.json). If auto-merge is enabled and CI passes, they merge automatically.
For PRs with non-digest changes (e.g., major version bumps), review manually before merging.
Update README Raptor Section
The "What Makes this Raptor Different?" section in README.md must be updated on every package or configuration change. The full section template is in finpilot-onboarding.
When to Update
| Change | Section to Update |
|---|
Added system package in build/10-build.sh | "Added Packages (Build-time)" |
| Added Brewfile package | "Added Applications (Runtime) → CLI Tools" |
| Added Flatpak | "Added Applications (Runtime) → GUI Apps" |
| Removed/disabled package or service | "Removed/Disabled" |
| Enabled/disabled systemd service | "Configuration Changes" |
| Desktop environment change | "Configuration Changes" |
Format
_Last updated: [date]_
Always update the date. Keep descriptions brief and user-focused, written for
typical Linux users, not developers.
Verify Signing
Keyless OIDC signing runs via the Sign and publish step in
.github/workflows/build-image.yml. Unsigned images fail the promotion release
gate, so leave it enabled. Full details: finpilot-templates.
Local Test Loop
Use the local test loop for rapid iteration before opening a PR.
Commands
just build
just build-qcow2
just run-vm-qcow2
Combined (Common Workflow)
just build && just build-qcow2 && just run-vm-qcow2
Alternative: ISO Testing
just build
just build-iso
just run-vm-iso
When to Run
| Scenario | Test |
|---|
| Added system package | just build + bootc container lint |
| Changed ujust command | just --list |
| Changed Brewfile | brew bundle check --file custom/brew/default.Brewfile |
| Changed Flatpak preinstall | Verify app ID on Flathub |
| Major base image change | Full loop: just build && just build-qcow2 && just run-vm-qcow2 |
PR vs Direct Push Policy
Always Open a PR to main
Direct pushes to main bypass validation and create untraceable changes. PRs
trigger pr-validation.yml and the validate-*.yml checks; branch protection
should require PRs with the validate status check (setup: finpilot-onboarding).
PR Best Practices
Use Conventional Commits and the change-type checklists — see
finpilot-pr-checklist.
Keeping OCI Digests Current via Renovate
Renovate handles digest updates automatically. It needs a valid RENOVATE_TOKEN
(setup: finpilot-onboarding), the Renovate workflow enabled, and auto-merge for
digest-only PRs. If Renovate stops creating PRs, run the Renovate section of
finpilot-troubleshooting.
Maintenance Schedule Recommendations
Weekly
- Review and merge Renovate PRs
- Check that
validate checks are passing on main
Monthly
- Run local test loop (
just build && just build-qcow2 && just run-vm-qcow2)
- Review and update README raptor section if any drift
- Check for security advisories on base image (via Renovate PRs or GitHub Security tab)
Quarterly
- Review and clean up old branches
- Verify
RENOVATE_TOKEN still valid
- Verify signing works (
cosign verify on the latest :stable image)
- Review
build/*.sh scripts for obsolete packages or patterns
Annually
- Review and bump Fedora major version (if desired)
- Update
FEDORA_MAJOR_VERSION ARG in Containerfile
- Test full build and deployment cycle
- Review and update documentation (
README.md, AGENTS.md, skills)
Common Rationalizations
| Rationalization | Reality |
|---|
| "I'll merge this Renovate PR without reading it — it's just a digest bump." | Always verify the file affected. A misconfigured Renovate rule could affect the wrong image. |
| "I'll update the README later when I have more changes." | Update incrementally. "Later" often means never, and users rely on README for current state. |
| "Local builds are optional since CI builds everything." | Local builds catch issues faster and don't burn CI minutes. The just build loop is essential. |
| "I'll push to main to save time." | PRs are cheap. Direct pushes bypass validation and create untraceable changes. |
| "Signing is too hard — I'll skip it." | Keyless OIDC signing is already enabled in the template — no setup, no secrets. |
Red Flags
- Renovate PRs sitting unmerged for weeks
- README raptor section missing or severely outdated
- No local builds run before PRs are opened
- Direct pushes to
main bypassing branch protection
- Signing step removed or disabled (promotion gate will block releases)
RENOVATE_TOKEN expired (Renovate workflow fails)
Verification
