From bf8230f6980ddcae7d57d25c1d5225e112e9598e Mon Sep 17 00:00:00 2001 From: Phoebus Date: Sun, 20 Sep 2026 02:42:50 -0700 Subject: [PATCH] docs(git): hardening docs, backup timer and issue/PR templates - scripts/backup-timer.sh installs/removes a daily systemd user timer running scripts/backup-git.sh (enabled locally; DEST should be a synced folder). - .forgejo/ISSUE_TEMPLATE/*.md and PULL_REQUEST_TEMPLATE.md with a safety checklist. - docs/GIT-WORKFLOW.md: branch protection, CI runner, SSH commit signing, backup timer and recommended git configuration. --- .forgejo/ISSUE_TEMPLATE/bug_report.md | 29 ++++++++++ .forgejo/ISSUE_TEMPLATE/feature_request.md | 21 +++++++ .forgejo/PULL_REQUEST_TEMPLATE.md | 21 +++++++ docs/GIT-WORKFLOW.md | 45 +++++++++++++++ scripts/backup-timer.sh | 65 ++++++++++++++++++++++ 5 files changed, 181 insertions(+) create mode 100644 .forgejo/ISSUE_TEMPLATE/bug_report.md create mode 100644 .forgejo/ISSUE_TEMPLATE/feature_request.md create mode 100644 .forgejo/PULL_REQUEST_TEMPLATE.md create mode 100755 scripts/backup-timer.sh diff --git a/.forgejo/ISSUE_TEMPLATE/bug_report.md b/.forgejo/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..39d75aa --- /dev/null +++ b/.forgejo/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,29 @@ +--- +name: Bug report +about: Report a defect in the installer or the installed system +title: "[bug] " +labels: bug +--- + +## What happened + +## What you expected + +## Steps to reproduce + +## Environment + +- Phoebus commit (`git rev-parse --short HEAD`): +- Installer: Rust (`installer-rs`) / Bash (`installer`) +- Tested in: disposable VM / physical hardware +- GPU / firmware if relevant: + +## Logs + +- Installer log: `/var/log/phoebus-installer/install.log` +- `systemctl --failed`, `journalctl -b -p warning` for boot issues + +## Safety check + +- [ ] This is not a request to weaken encryption, signing, boot or disk + protection for convenience. diff --git a/.forgejo/ISSUE_TEMPLATE/feature_request.md b/.forgejo/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..6e184ab --- /dev/null +++ b/.forgejo/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,21 @@ +--- +name: Feature request +about: Suggest an improvement or a new capability +title: "[feat] " +labels: enhancement +--- + +## Problem + +What user problem does this solve? + +## Proposed change + +## Alternatives considered + +## Fit with the project + +- [ ] Prefers upstream Gentoo/tooling rather than new code +- [ ] Does not require the LLM for the normal path +- [ ] Keeps the proven boot path stable (or the trade-off is explained) +- [ ] Checked against `docs/ROADMAP.md` priorities diff --git a/.forgejo/PULL_REQUEST_TEMPLATE.md b/.forgejo/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..dd040ad --- /dev/null +++ b/.forgejo/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,21 @@ +## What and why + +## How it was verified + +- [ ] `make test` passes (Bash + Rust suites) +- [ ] `cargo fmt --check` and `cargo clippy` clean +- [ ] Disposable-VM verified if this touches install, storage, encryption, boot, + kernel or desktop +- [ ] `docs/CHANGELOG.md` and `docs/STATUS.md` updated if behavior or + verification changed + +## Safety + +- [ ] No secrets, ISO or build output committed +- [ ] Does not weaken LUKS2, Btrfs, systemd, UEFI or disk protection +- [ ] Does not globally enable `~amd64` or disable signature verification +- [ ] Does not give the AI a shell, root, secrets or home-directory access + +## Notes for the reviewer + +Anything uncertain, deferred or intentionally out of scope. diff --git a/docs/GIT-WORKFLOW.md b/docs/GIT-WORKFLOW.md index ec3d6c7..5b22859 100644 --- a/docs/GIT-WORKFLOW.md +++ b/docs/GIT-WORKFLOW.md @@ -123,6 +123,51 @@ Bypass for a genuine emergency with `git commit --no-verify`, or set `SKIP_PHOEBUS_HOOKS=1`. Set `PHOEBUS_PRECOMMIT_RUST=1` to also run `cargo test --workspace` in the hook. +## Repository settings and hardening + +Current state: + +- Public repository with description and topics set. +- `main` protected: owner-only direct push; force-push and deletion blocked + (`scripts/forgejo.sh protect`, remove with `unprotect`, or `make protect`). +- Issue and PR templates in `.forgejo/`. +- Daily git bundle backup via the `phoebus-backup.timer` user timer + (`scripts/backup-timer.sh status`). It is **local** by default; point + `enable DEST` at a synced/remote folder for a genuinely off-box copy, since + the only git remote is one VPS. + +### CI runner (optional) + +`.forgejo/workflows/ci.yml` mirrors the local gates but only runs once a +Forgejo Actions runner is registered. Install `act_runner` on a machine, +register it (Site Administration -> Actions -> Runners, or +`act_runner register --instance https://git.phoebus.club --token `), and +run it as a service. Until then, run `make test` before pushing. + +### Commit signing (optional) + +For "Verified" commits, sign with an SSH key and register the **public** key as +a signing key in Forgejo (User Settings -> SSH/GPG Keys): + +```sh +git config --local gpg.format ssh +git config --local user.signingkey ~/.ssh/id_ed25519.pub +git config --local commit.gpgsign true +``` + +Never commit private keys. `git config --local` keeps this scoped to the repo. + +### Recommended git configuration + +```sh +git config --global merge.conflictstyle zdiff3 +git config --global rerere.enabled true +git config --global fetch.prune true +git config --global rebase.autosquash true +git config --global pull.ff only +git config --global diff.algorithm histogram +``` + ## Branching and releases - Trunk-based: `main` is always green. Short-lived branches are fine for risky diff --git a/scripts/backup-timer.sh b/scripts/backup-timer.sh new file mode 100755 index 0000000..b570e9a --- /dev/null +++ b/scripts/backup-timer.sh @@ -0,0 +1,65 @@ +#!/usr/bin/env bash +# Install, remove or inspect a systemd user timer that runs the git bundle +# backup daily. +# +# scripts/backup-timer.sh enable [DEST_DIR] +# scripts/backup-timer.sh disable +# scripts/backup-timer.sh status +# +# DEST_DIR defaults to ~/backups/phoebus. Point it at a synced/remote folder +# (Nextcloud, Dropbox, rclone mount, ...) for a genuinely off-box copy, since +# the only git remote is a single VPS. + +set -euo pipefail + +root="$(git rev-parse --show-toplevel)" +cd "$root" + +unit="phoebus-backup" +unit_dir="$HOME/.config/systemd/user" + +case "${1:-status}" in + enable) + dest="${2:-$HOME/backups/phoebus}" + mkdir -p "$unit_dir" "$dest" + cat >"$unit_dir/$unit.service" <"$unit_dir/$unit.timer" <<'EOF' +[Unit] +Description=Daily Phoebus git bundle backup + +[Timer] +OnCalendar=daily +Persistent=true + +[Install] +WantedBy=timers.target +EOF + systemctl --user daemon-reload + systemctl --user enable --now "$unit.timer" + echo "enabled $unit.timer -> $dest" + echo "note: set DEST to a synced/remote folder for an off-box copy." + ;; + disable) + systemctl --user disable --now "$unit.timer" 2>/dev/null || true + rm -f "$unit_dir/$unit.service" "$unit_dir/$unit.timer" + systemctl --user daemon-reload 2>/dev/null || true + echo "disabled $unit.timer" + ;; + status) + systemctl --user list-timers "$unit.timer" --no-pager 2>/dev/null || true + systemctl --user status "$unit.timer" --no-pager 2>/dev/null || \ + echo "$unit.timer is not installed" + ;; + *) + echo "usage: $0 enable [DEST_DIR] | disable | status" >&2 + exit 2 + ;; +esac