vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add canonical "Our Git Server" section (gitea.redbearos.org)

Browse Source 
Rewrite the scattered git-server references into a single canonical
section in README.md and a comprehensive operator section in
local/AGENTS.md.

- README.md: new top-level "Our Git Server" section with connection
  details table (token field left as placeholder per session-only
  token policy).
- local/AGENTS.md: new "OUR GIT SERVER" section covering connection
  details, repo map, clone/auth/remote-setup recipes, cookbook
  auth via .netrc, push runbook, API quick reference, and a full
  operator runbook including credential-recovery and
  accidental-commit mitigation.

Tokens are explicitly NOT stored anywhere in tracked files. Clones
and authenticated operations must use credential helper, .netrc,
or REDBEAR_GITEA_TOKEN env var.

Also normalizes the lowercase-slug note (gitea normalizes RedBear-OS
to redbear-os) and the related-repos table.
This commit is contained in:
vasilito
2026-06-29 19:56:06 +03:00
parent 44d434e369
commit 0c60adc6b5
2 changed files with 190 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+24 -1
View File
@@ -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
local/AGENTS.md
+166
View File
@@ -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 <token>`)
> - 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 <token from CI secret, never literal in this repo>
```
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 <branch>
```
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/<component>/` becomes desynced, recover from
`https://gitea.redbearos.org/vasilito/redbear-os-<component>` 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