# 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: ```sh 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: ```sh 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: ```sh 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) ```sh 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: ```sh 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: ```sh 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.