phoebus_os/docs/GIT-WORKFLOW.md
Phoebus fc64793aec docs: update references after retiring the Bash installer
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.
2026-09-20 04:00:19 -07:00

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):

  1. scans staged files for secrets (scripts/check-secrets.sh);
  2. blocks staged *.iso, *.qcow2 and files larger than 5 MiB;
  3. 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.
  • 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):

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.

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 work; merge with a conventional merge/squash.
  • Releases are annotated tags vX.Y.Z with the manifest produced by phoebus-release. Never replace latest.iso until phoebus-release verify passes.
  • Never rewrite published history (push --force to main is forbidden). Fix mistakes with a new fix: 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

  1. git log --oneline -20 and head docs/CHANGELOG.md for context.
  2. Work as described in AGENTS.md.
  3. Before committing: scripts/check-secrets.sh and the test gates.
  4. Commit with scripts/agent-commit.sh (or git commit), then scripts/publish.sh.
  5. Confirm git status is clean and the push succeeded.