diff --git a/README.md b/README.md index ba8ad6c8a4..20ddb4fbcf 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,26 @@ Red Bear OS is a general-purpose, Unix-like operating system with a **microkerne - **Modern subsystems** — USB, Wi‑Fi, Bluetooth, ext4, GRUB, D-Bus - **Offline-first builds** — reproducible from archived, BLAKE3-verified sources +## Our Git Server + +Red Bear OS lives on a self-hosted Gitea instance at **https://gitea.redbearos.org**. +This is the canonical home for the fork — there is no GitHub / GitLab / Codeberg +mirror that is authoritative. + +| Field | Value | +|----------|------------------------------------------------------| +| Host | `https://gitea.redbearos.org` | +| User | `vasilito` | +| Token | *(session-only — never stored in repo)* | +| Web UI | `https://gitea.redbearos.org/vasilito` | +| Main repo| `https://gitea.redbearos.org/vasilito/RedBear-OS` | + +> **Token policy.** The `vasilito` token is a per-session credential and **must +> never** be committed to any tracked file. Use `git credential.helper` (store / +> cache / libsecret), `~/.netrc`, or `$REDBEAR_GITEA_TOKEN` env var. See +> [`local/AGENTS.md` § Our Git Server](./local/AGENTS.md) for the full operator +> runbook, mirror list, API reference, and recovery procedure. + ## Quick Start ### Prerequisites @@ -37,10 +57,13 @@ See the [Redox Build Guide](https://doc.redox-os.org/book/podman-build.html) for ### Build & Run ```bash -# Clone +# Clone (read-only) git clone https://gitea.redbearos.org/vasilito/RedBear-OS.git cd RedBear-OS +# Authenticated clone (one-off) — supply token via env var, not literal here +git clone https://vasilito:${REDBEAR_GITEA_TOKEN}@gitea.redbearos.org/vasilito/RedBear-OS.git + # Recommended: use the Red Bear wrapper ./local/scripts/build-redbear.sh redbear-mini # Text-only target ./local/scripts/build-redbear.sh redbear-full # Desktop-capable target diff --git a/local/AGENTS.md b/local/AGENTS.md index 098f770e0e..3bf2a352cb 100644 --- a/local/AGENTS.md +++ b/local/AGENTS.md @@ -49,6 +49,172 @@ Red Bear OS must remain a free/libre project. - When a dependency is dual-licensed under multiple free/open licenses, choose and document the option that is compatible with the Red Bear project surface. - For the greeter/login stack specifically, the current SHA-crypt verifier path is the pure-Rust `sha-crypt` crate, licensed `MIT OR Apache-2.0`; Red Bear treats it under the MIT option for compatibility with the project's free-software policy. +## OUR GIT SERVER + +Red Bear OS is hosted on a self-hosted Gitea instance at **gitea.redbearos.org**. +This is the only canonical home for our fork — there is no GitHub / GitLab / Codeberg +mirror that is treated as authoritative. All Red Bear custom work, including local +recipe sources that have no upstream, lives here. + +### Connection details + +| Field | Value | +|----------|------------------------------------------------------| +| Host | `https://gitea.redbearos.org` | +| User | `vasilito` | +| Token | *(session-only — not stored in repo; see Token Policy below)* | +| Web UI | `https://gitea.redbearos.org/vasilito` | +| API root | `https://gitea.redbearos.org/api/v1` | + +> **Token Policy (NEVER STORE OPERATOR TOKENS IN TRACKED DOCS).** +> The `vasilito` Gitea token is treated as an ephemeral per-session credential. +> It is supplied at runtime via: +> - `git credential.helper` (preferred — `store` / `cache` / `libsecret`) +> - `~/.netrc` (`machine gitea.redbearos.org login vasilito password `) +> - the `REDBEAR_GITEA_TOKEN` env var (read by CI scripts) +> - the URL itself, for one-off authenticated clones (visible in shell history — only acceptable in disposable sandboxes) +> +> **Never** commit a token to `local/`, `docs/`, `README.md`, or any +> other tracked file. **Never** bake it into `.git/config` on a shared +> machine. **Never** paste it into chat logs, screenshots, error reports, +> or shell recordings. If a token leaks, rotate it immediately via the +> Gitea web UI (`https://gitea.redbearos.org/user/settings/applications`). +> +> When this file is updated, leave the **Token** row as a placeholder. +> The actual value lives only on the operator's workstation, in CI +> secrets, or in `pass`/`1Password`/`Vault`. + +### Repositories under our Gitea + +The following repos are tracked under the `vasilito` user. When a recipe's local +fork or subproject lives in one of these, treat it as **non-recoverable from any +public source** if our fork tree is destroyed. + +| Repo path | Purpose | +|------------------------------------|----------------------------------------------------------| +| `vasilito/RedBear-OS` | **Main fork of Redox OS** (this repo, build system) | +| `vasilito/redbear-os` | Lowercase-slug mirror of the same repo (Gitea-normalized) | +| `vasilito/redbear-os-base` | Local fork of `redox-os/base` (used by `local/sources/base`) | +| `vasilito/redbear-os-kernel` | Local fork of `redox-os/kernel` (used by `local/sources/kernel`) | +| `vasilito/redbear-os-relibc` | Local fork of `redox-os/relibc` (used by `local/sources/relibc`) | + +> **Naming note.** Gitea normalizes repository slugs to lowercase. Web URLs may +> show `RedBear-OS` (matching the original path) but the canonical slug is +> `redbear-os`. Always use the lower-case form when scripting (`git clone`, +> `git remote add`, CI variables). The two rows above refer to the same repo. + +### How to clone + +```bash +# Public read-only clone (no token) +git clone https://gitea.redbearos.org/vasilito/RedBear-OS.git +cd RedBear-OS + +# Authenticated clone — supply the token ONLY at the command line +# (visible in shell history — only acceptable in disposable sandboxes) +git clone https://vasilito:$REDBEAR_GITEA_TOKEN@gitea.redbearos.org/vasilito/RedBear-OS.git +``` + +### Configuring a remote on an existing clone + +```bash +# Read-only remote +git remote add origin https://gitea.redbearos.org/vasilito/RedBear-OS.git + +# Authenticated remote — use credential helper, NOT a token in the URL +git config --global credential.helper store # or libsecret / cache +git pull # prompts for user + token, stores in ~/.git-credentials + +# Verify (URL should NOT contain the token) +git remote -v +``` + +If a token has ended up in `.git/config` (e.g. from a paste-into-URL mistake), +wipe it with `git credential erase` or `pass`, then re-add the remote URL +without credentials. + +### Authentication for the cookbook + +The cookbook tool (`src/bin/repo.rs`) reads HTTPS Basic-auth credentials from +`.gitconfig`, `.netrc`, or the URL itself when fetching Red Bear local-fork +recipes. The `REDBEAR_ALLOW_PROTECTED_FETCH=1` env var (set by +`build-redbear.sh --upstream`) authorizes the fetch; the actual credentials +must be supplied separately. + +For CI / Docker builds, mount a `.netrc` (or the team's secret manager): + +``` +machine gitea.redbearos.org +login vasilito +password +``` + +The token row above is intentionally not filled in. CI should template it from +`$REDBEAR_GITEA_TOKEN` (or the equivalent Vault / 1Password secret reference). + +### Pushing changes + +```bash +# Recommended: pre-flight check before any push +git status --short +git diff --stat HEAD +git fetch origin +git log --oneline origin/$(git branch --show-current)..HEAD + +# Push (uses credential helper, prompts once per session if needed) +git push origin +``` + +CI rule: **never force-push to `main` / `master` / `0.x` branches**. Force-push is +only permitted on personal feature branches that have not yet been merged. + +### Gitea API quick reference + +For ad-hoc queries, supply the token via env var (never inline in the command +for anything that lands in a shared shell history, log, or CI artifact): + +```bash +# List repos visible to vasilito +curl -sS -H "Authorization: token $REDBEAR_GITEA_TOKEN" \ + https://gitea.redbearos.org/api/v1/users/vasilito/repos | jq '.[].full_name' + +# List open issues on the main repo (public endpoint, no token) +curl -sS https://gitea.redbearos.org/api/v1/repos/vasilito/RedBear-OS/issues?state=open | jq +``` + +For mirroring or bulk migration tasks, see `local/scripts/sync-versions.sh` and +`local/scripts/check-upstream-releases.sh` for examples of Gitea-aware shell +scripts. + +### Operator runbook + +If the server is unreachable: + +1. Check `https://gitea.redbearos.org/` in a browser. If down, halt all pushes. +2. If a credential has leaked, rotate the token via the Gitea web UI: + `https://gitea.redbearos.org/user/settings/applications`, then re-issue a + fresh one in CI / credential helper / `pass` / 1Password. **Do not** paste the + new token into any file in this repo. +3. If `local/sources//` becomes desynced, recover from + `https://gitea.redbearos.org/vasilito/redbear-os-` rather than + from upstream Redox. + +### Recovery from credential loss + +If the Gitea user has lost access to the token entirely: + +1. SSH/console into the Gitea host as an admin, or have an admin reset + the user's password. +2. Log in via web UI, generate a new personal access token under + `Settings → Applications → Manage Access Tokens`. +3. Push the new token into the team's secret store only. Do **not** commit it. +4. Update the running CI runners and any local `.netrc` / credential helper stores + on workstations — none of which live in this repo. + +If the token has been committed to this repo by mistake, treat it as compromised: +rotate immediately, then `git filter-repo` (or BFG) the offending file from +history and force-push the rewritten history on a feature branch before merging. + Build flow: ``` make all CONFIG_NAME=redbear-full