Point AGENTS.md, README.md and the docs at the Rust-only toolchain and the moved VM-BOOT-VERIFICATION.md, and drop the Bash installer from DEVELOPMENT.md.
6.6 KiB
Git workflow and public-repository migration
What is tracked
Tracked: source (installer/tests/vm/, installer-rs/crates/, scripts/,
.githooks/), Cargo.toml/Cargo.lock, documentation (docs/, AGENTS.md,
README.md, installer-rs/README.md) and tests (installer-rs/**/tests/).
Ignored (see .gitignore): the reference ISO and other images, installer-rs/target/,
__pycache__, .agent-shell/ transcripts, and any secret material
(*.pw, *.key, *.pem, credentials).
Hosted forge and remote
The project is hosted on Forgejo at git.phoebus.club:
remote: origin
url: git@git.phoebus.club:phoebus/phoebus_os.git
web: https://git.phoebus.club/phoebus/phoebus_os
SSH uses the Host git.phoebus.club entry in ~/.ssh/config (user git,
port 2222, laptop key), so the short git@git.phoebus.club:... form works. The
repository was created by Forgejo push-to-create, which uses the account's
default visibility; check that the repository is public in
Settings -> General (or PATCH /api/v1/repos/phoebus/phoebus_os with
{"private":false} using an API token).
scripts/publish.sh pushes the current branch to the configured remote after
re-running the checks:
scripts/publish.sh # origin + current branch
scripts/publish.sh origin main
git push origin v0.1.0 # publish release tags explicitly
API token setup (one command after the browser step)
Creating a token is the only manual step because it needs your browser login:
User Settings -> Applications -> Generate New Token, name it (e.g.
phoebus-cli), set Repository and Organization Access to All (public,
private, and limited) (the repo starts private), and give repository
Read and write (everything else "No access"). Then:
scripts/forgejo.sh init # or: make forgejo-init
init prompts for the token with hidden input, stores it at
~/.config/phoebus/forgejo.token (0600), verifies the account and makes the
repository public. The token is never printed, never passed on a command line
and never committed.
Other helpers:
scripts/forgejo.sh repo-info
scripts/forgejo.sh list-repos
scripts/forgejo.sh set-public # or: make public
scripts/forgejo.sh create-release v0.2.0 --name v0.2.0 # or: make release TAG=v0.2.0
The helper reads $FORGEJO_TOKEN if set, otherwise the token file, and uses a
0600 temp curl config so the token stays out of ps, logs and history.
One-time migration (already performed)
cd /path/to/phoebus_os
git init -b main
git add -A
git commit -m "chore: import Phoebus OS installer and Rust migration"
# ... further commits for docs, tooling and the Makefile ...
git config core.hooksPath .githooks
git remote add origin git@git.phoebus.club:phoebus/phoebus_os.git
git push -u origin main
git push origin v0.1.0
For a fresh clone on another machine:
git clone git@git.phoebus.club:phoebus/phoebus_os.git
cd phoebus_os
scripts/setup-hooks.sh # re-enable the committed hooks
Ongoing loop for a work session
read AGENTS.md
-> inspect docs/ROADMAP.md and git log
-> implement the smallest correct change
-> run the quality gates
-> update docs/CHANGELOG.md and docs/STATUS.md
-> commit (conventional message)
-> push
An AI session must commit the work it does. The one-line helper:
scripts/agent-commit.sh "feat(rust): add typed SystemAction broker
Adds a closed action schema and a privileged broker. Verified with
cargo test --workspace."
agent-commit.sh refuses to commit if the secret scan finds a credential or if
a staged file is too large, then runs the fast tests.
Hooks
.githooks/pre-commit (enabled with git config core.hooksPath .githooks):
- scans staged files for secrets (
scripts/check-secrets.sh); - blocks staged
*.iso,*.qcow2and files larger than 5 MiB; - runs the fast Bash test suite.
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.
mainprotected: owner-only direct push; force-push and deletion blocked (scripts/forgejo.sh protect, remove withunprotect, ormake protect).- Issue and PR templates in
.forgejo/. - Daily git bundle backup via the
phoebus-backup.timeruser timer (scripts/backup-timer.sh status). It is local by default; pointenable DESTat 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):
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
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:
mainis always green. Short-lived branches are fine for risky work; merge with a conventional merge/squash. - Releases are annotated tags
vX.Y.Zwith the manifest produced byphoebus-release. Never replacelatest.isountilphoebus-release verifypasses. - Never rewrite published history (
push --forcetomainis forbidden). Fix mistakes with a newfix:commit.
Secret policy
- Never commit passwords, LUKS passphrases, API keys or tokens.
- Secrets are supplied at runtime through 0600 files or stdin and registered with the redactor.
- The pre-commit scan is a safety net, not a licence to be careless.
What a future session should do
git log --oneline -20andhead docs/CHANGELOG.mdfor context.- Work as described in
AGENTS.md. - Before committing:
scripts/check-secrets.shand the test gates. - Commit with
scripts/agent-commit.sh(orgit commit), thenscripts/publish.sh. - Confirm
git statusis clean and the push succeeded.