phoebus_os/docs/GIT-WORKFLOW.md
Phoebus 1d37fbc1b8 ci(release): fail closed and bind gates to the candidate artifact
Make a passing CI/release result mean the checks actually ran.

- .forgejo/workflows/ci.yml is fail-closed: it provisions the pinned
  toolchain or fails, then runs one 'make ci' (fmt-check, clippy, workspace
  tests, VM-harness safety tests, release build, static installer build).
- Pin stable Rust 1.93.1 in installer-rs/rust-toolchain.toml; run cargo gates
  with --locked for reproducible dependencies.
- phoebus-release gates now records passed/failed/blocked/skipped/not_run
  (only passed is a pass), executes real host gate commands, and imports the
  existing VM-harness results.json instead of a competing harness. Gates with
  no automation are always blocked.
- Bind gate reports and harness evidence to a candidate name+SHA-256
  (--candidate; PHOEBUS_VM_ARTIFACT[_SHA256]); stale or unbound evidence is
  failed, never passed.
- publish refuses unless the report is candidate-bound and all-passed, the
  manifest verifies the artifact and a detached signature verifies; atomic
  publish preserves and restores the previous release on failure.
- vmsafety.Results records the verified artifact digest; 3 new Python tests.
- 20 new Rust regression tests; ADR 0012 and docs updated.

Verified locally: make ci (364 Rust tests, 19 harness tests, release and
static builds) exit 0; static binary is static-pie linked. CI runner, VM and
model gates remain unexecuted here.
2026-09-22 07:34:27 -07:00

6.9 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. optionally runs the Rust suite (set PHOEBUS_PRECOMMIT_RUST=1 to enable).

Bypass for a genuine emergency with git commit --no-verify, or set SKIP_PHOEBUS_HOOKS=1.

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.

.forgejo/workflows/ci.yml runs make ci (fmt, clippy, workspace tests, VM-harness safety tests, release build, static installer build). It is fail-closed: if the runner lacks a Rust toolchain it fails the job rather than skipping checks, so a green result always means the checks ran. It 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 with a rustup-provisioned toolchain (or cargo + rustfmt + clippy). Until then, run make ci 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.