docs(git): hardening docs, backup timer and issue/PR templates
Some checks are pending
ci / test (push) Waiting to run
Some checks are pending
ci / test (push) Waiting to run
- 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.
This commit is contained in:
parent
b6b9630148
commit
bf8230f698
5 changed files with 181 additions and 0 deletions
29
.forgejo/ISSUE_TEMPLATE/bug_report.md
Normal file
29
.forgejo/ISSUE_TEMPLATE/bug_report.md
Normal file
|
|
@ -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.
|
||||||
21
.forgejo/ISSUE_TEMPLATE/feature_request.md
Normal file
21
.forgejo/ISSUE_TEMPLATE/feature_request.md
Normal file
|
|
@ -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
|
||||||
21
.forgejo/PULL_REQUEST_TEMPLATE.md
Normal file
21
.forgejo/PULL_REQUEST_TEMPLATE.md
Normal file
|
|
@ -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.
|
||||||
|
|
@ -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
|
`SKIP_PHOEBUS_HOOKS=1`. Set `PHOEBUS_PRECOMMIT_RUST=1` to also run
|
||||||
`cargo test --workspace` in the hook.
|
`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 <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
|
## Branching and releases
|
||||||
|
|
||||||
- Trunk-based: `main` is always green. Short-lived branches are fine for risky
|
- Trunk-based: `main` is always green. Short-lived branches are fine for risky
|
||||||
|
|
|
||||||
65
scripts/backup-timer.sh
Executable file
65
scripts/backup-timer.sh
Executable file
|
|
@ -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" <<EOF
|
||||||
|
[Unit]
|
||||||
|
Description=Phoebus OS git bundle backup
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=oneshot
|
||||||
|
WorkingDirectory=$root
|
||||||
|
ExecStart=$root/scripts/backup-git.sh $dest
|
||||||
|
EOF
|
||||||
|
cat >"$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
|
||||||
Loading…
Add table
Reference in a new issue