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.
198 lines
6.9 KiB
Markdown
198 lines
6.9 KiB
Markdown
# 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:
|
|
|
|
```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. 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.
|
|
|
|
### CI runner (recommended)
|
|
|
|
`.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):
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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.
|