docs: gitea-local-fork end-to-end publishing flow

Rescued from the second flake-hub checkout (~/projects/flake-hub) before
that working copy was removed. Documents the path from local Gitea fork
to the attic binary cache.

docs/publishing-gitea-local-fork.md

@@ -0,0 +1,174 @@
+# Publishing `gitea-local-fork`
+
+End-to-end flow for taking a change in Oleks's local gitea fork
+(`/home/oleks/projects/gitea`, branch `oleks/main`) all the way to a
+binary in the `attic-infra-cache-k3s-1` cache, ready for any consumer
+to fetch instead of recompiling Go 1.26.3 locally.
+
+## Step-by-step
+
+### 1. Develop in the gitea fork
+
+```bash
+cd ~/projects/gitea
+# work on oleks/main (the fork integration tip)
+git commit -m "..."
+git push oleks oleks/main:main
+```
+
+Lands on `git.oleks.space/oleks/gitea` at `refs/heads/main`.
+
+This step alone does **not** trigger any CI on flake-hub — the binding
+contract is the flake-hub pin commit in step 2.
+
+### 2. Bump the pin in flake-hub
+
+```bash
+cd ~/projects/nix-customs/flake-hub
+just gitea-update
+```
+
+Under the hood, `scripts/update-gitea-local-fork.sh`:
+
+1. **Wipes stale unstable tags** — `git push oleks :refs/tags/v*-unstable-*`
+   so `nix-update` sees only clean semver tags (`v1.26.0` etc.) when
+   constructing the new version.
+2. **Bumps the pin** —
+
+   ```bash
+   nix run nixpkgs#nix-update -- \
+       --flake gitea-local-fork \
+       --version=branch=main \
+       --build
+   ```
+
+   Updates `rev`, `vendorHash`, `pnpmDeps` hash, and `version` (formatted
+   as `<latest-semver-tag>-unstable-<commit-date>`).
+3. **Tags the gitea fork** at the new rev with `v<version>` and pushes
+   the tag. **This is the load-bearing step:** the tag makes the rev
+   reachable forever, surviving any future rebase / force-push of
+   `oleks/main`.
+4. **Commits + pushes flake-hub** — the bumped `packages/gitea-local-fork.nix`
+   lands on `git.oleks.space/oleks/flake-hub` `main`.
+
+### 3. Woodpecker picks up the flake-hub push
+
+Pipeline auto-triggers from `.woodpecker/amd64.yaml` and `.woodpecker/arm64.yaml`
+running in parallel. Each workflow:
+
+1. Clones `oleks/flake-hub` using the `gitea_clone_token` secret.
+2. Runs `ci/setup.sh` — configures `/etc/hosts` to pin `armer`
+   directly (bypassing Cloudflare upload-size limits via hairpin NAT)
+   and writes the trusted substituters / public keys to `/etc/nix/nix.conf`.
+3. Runs `ci/build.py <arch>` — for each package (including
+   `gitea-local-fork` on `x86_64-linux` and `aarch64-linux`):
+
+   ```bash
+   nix build .#packages.<arch>.gitea-local-fork --print-build-logs ...
+   attic push attic-infra-cache-k3s-1 <closure>
+   ```
+
+   Authenticates the push with `ATTIC_TOKEN` against
+   `https://nix-cache-upload.oleks.space`.
+
+### 4. Closure lives in attic
+
+After both arch workflows succeed, the closure is queryable from:
+
+- **Cache URL:** `https://nix-cache-custom.oleks.space/attic-infra-cache-k3s-1`
+- **Public key:** `attic-infra-cache-k3s-1:qYSNK3DmttQXCFqn1t50qoWGtQNPRFWq9mgQjD05DeU=`
+
+### 5. Consume from cache
+
+Anyone (or any host) can pull the binary instead of building:
+
+<!-- markdownlint-disable MD013 -->
+```bash
+just gitea-run
+# or, equivalently:
+nix run \
+    --extra-substituters "https://nix-cache-custom.oleks.space/attic-infra-cache-k3s-1" \
+    --extra-trusted-public-keys "attic-infra-cache-k3s-1:qYSNK3DmttQXCFqn1t50qoWGtQNPRFWq9mgQjD05DeU=" \
+    git+https://git.oleks.space/oleks/flake-hub#gitea-local-fork
+```
+<!-- markdownlint-enable MD013 -->
+
+## Diagram
+
+```text
+┌────────────────────────────────────────────────────────────────────────┐
+│  1. ~/projects/gitea  (branch oleks/main)                              │
+│     ─ git push oleks oleks/main:main ─►  oleks/gitea refs/heads/main   │
+└────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌────────────────────────────────────────────────────────────────────────┐
+│  2. ~/projects/nix-customs/flake-hub                                   │
+│     ─ just gitea-update                                                │
+│         a. wipe v*-unstable-* tags on fork                             │
+│         b. nix-update → bump rev/hashes/version                        │
+│         c. tag fork at new rev: v<version> ─► push                     │
+│         d. commit + push flake-hub origin/main                         │
+└────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌────────────────────────────────────────────────────────────────────────┐
+│  3. ci.oleks.space  pipeline auto-fires                                │
+│     amd64 + arm64 (parallel):                                          │
+│       clone → ci/setup.sh → ci/build.py <arch>                         │
+│         ─ nix build .#packages.<arch>.gitea-local-fork                 │
+│         ─ attic push attic-infra-cache-k3s-1 <closure>                 │
+└────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌────────────────────────────────────────────────────────────────────────┐
+│  4. attic-infra-cache-k3s-1                                            │
+│     URL: https://nix-cache-custom.oleks.space/attic-infra-cache-k3s-1  │
+└────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌────────────────────────────────────────────────────────────────────────┐
+│  5. Consumer:  just gitea-run  /  nix run …#gitea-local-fork           │
+│     ─ closure pulled from cache, no recompile                          │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+## Secrets
+
+Both are Woodpecker repo secrets on `oleks/flake-hub` (never in code):
+
+- `gitea_clone_token` — clone flake-hub source; netrc for `fetchgit` of
+  the fork.
+- `attic_token` — authenticate `attic push` against
+  `nix-cache-upload.oleks.space`.
+
+## Why the dance with tags in step 2c
+
+The fork's `oleks/main` branch is rebaseable. `fetchgit` in the
+derivation resolves by `rev`, so the rev must remain reachable from
+*some* ref on the remote. Tags are immutable. The
+`v<version>` tag created at update time becomes the load-bearing
+reference: even if `oleks/main` later gets force-pushed and the rev
+falls off the branch, the tag keeps it alive (and Gitea won't GC it).
+
+## Failure points to watch
+
+- **Step 2c — tag push rejected.** Check `oleks` remote auth in your
+  shell; the pre-push hook also runs lint.
+- **Step 3 build — first cold build ≈10–15 min/arch, later ≈1–2 min.**
+  Normal; Go 1.26.3 compiles from source.
+- **Step 3 attic — push hangs or 413.** `ci/setup.sh` pins armer in
+  `/etc/hosts` to bypass the Cloudflare 100 MB upload cap; confirm the
+  pin survived.
+- **Step 5 consume — cache miss, recompile locally.** Check the closure
+  landed (`attic info` or browse the cache URL) and that the public key
+  matches.
+
+## Reference
+
+- Derivation: `packages/gitea-local-fork.nix`
+- Flake attr: `flake.nix` → `packages.<system>.gitea-local-fork`
+- Update script: `scripts/update-gitea-local-fork.sh` *(untracked, local-only)*
+- Pipelines: `.woodpecker/amd64.yaml`, `.woodpecker/arm64.yaml`
+- Build driver: `ci/build.py`
+- Justfile recipes: `just gitea-build`, `just gitea-update`, `just gitea-run`