phoebus_os/docs/GIT-WORKFLOW.md
Phoebus 2e3888feeb docs(git): record the Forgejo remote and clone/setup steps
Documents git.phoebus.club:phoebus/phoebus_os (SSH via the port-2222 alias),
push-to-create visibility, publish.sh usage and the post-clone hook setup.
2026-09-20 02:12:21 -07:00

4 KiB

Git workflow and public-repository migration

What is tracked

Tracked: source (installer/, installer-rs/crates/, scripts/, .githooks/), Cargo.toml/Cargo.lock, documentation (docs/, AGENTS.md, README.md, installer/doc/, installer-rs/README.md), installer configs and 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

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.

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.