phoebus_os/docs/GIT-WORKFLOW.md
Phoebus e680084f83 feat(git): add Forgejo API helper and one-command token setup
Adds scripts/forgejo.sh: 'init' prompts for the token with hidden input,
stores it 0600 at ~/.config/phoebus/forgejo.token, verifies the account and
makes the repository public. Also whoami/repo-info/set-public/list-repos/
create-repo/create-release, using a 0600 temp curl config so the token never
appears in argv, logs or history. Wires make forgejo-init/public/release and
documents the flow in docs/GIT-WORKFLOW.md.
2026-09-20 02:25:48 -07:00

150 lines
5 KiB
Markdown

# 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.