block / block/buzz

Docs: no end-to-end guide for hosting a repository on your relay; implemented access model diverges from VISION_PROJECTS

Open
#4,226 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

**Motivation**

The pieces needed to host a repository on your own relay all exist and work — but no single document connects them, and the one vision doc that covers the area describes a different access model than the one implemented. A self-hoster who enables the Projects preview feature has no discoverable path from "empty Projects page" to "working `git push`.

We migrated a real repository onto relay-hosted git in 2026-08 and needed source reading for nearly every step. The knowledge is currently split across (all verified present on `main` @ `ac4fa13`, 2026-08-01):

| Fact | Only documented in |
|---|---|
| `buzz repos create` publishes the kind:30617 announcement | CLI `--help` |
| `--channel` binding **is** the git ACL; without it clone/fetch/push fail | CLI `--help` + code comments (`crates/buzz-cli/src/commands/repos.rs:221` — "the tag is the git ACL") |
| Canonical clone URL is `/git//` | `desktop/src/features/projects/lib/projectCloneUrl.ts` comments |
| The relay seeds an empty repo on announce, so it's immediately pushable | `desktop/src-tauri/src/managed_agents/nest_skill.md` |
| Credential helper setup + git 2.46+ requirement | `crates/git-credential-nostr/README.md` |
| Read/push access resolves by **channel membership** (`get_member_role` against the bound channel, `Bot → Member`) | source only (`crates/buzz-relay/src/api/git/transport.rs:456`, `policy.rs:381`, `binding.rs`) |

That last row is the one most likely to surprise people: `VISION_PROJECTS.md` (lines 27-39) leads with `maintainers` tags, `buzz-protect` push-allowed lists, and NIP-OA owner inheritance — but the implemented gate is channel-membership resolution against the `buzz-channel` binding. Reading the vision doc gives you the wrong mental model of who can clone and push to your repo.

**Proposed solution**

One `docs/` page — "Host a repository on your relay" — walking announce → channel binding → clone URL → credential helper → push, with the access model stated plainly (channel membership, not the vision doc's protection lists) and the macOS credential-helper caveat inline.

I'm happy to draft this page as a PR if maintainers agree the shape is right — that's why this is an issue first.

**Alternatives considered**

- Expanding `crates/git-credential-nostr/README.md` — but that crate README is about auth only; the announce/bind/seed/ACL flow belongs at the repo docs level.
- Waiting for the vision to converge with the implementation — but self-hosters are hitting this now, and several recent issues (below) are downstream of exactly this discoverability gap.

**Additional context**

Related issues (searched open and closed): #2877 and #3539 documented the era when shipped clients couldn't emit the `buzz-channel` tag at all; the CLI *can* now (`repos create --channel`, `crates/buzz-cli/src/lib.rs:1135`), which arguably makes the missing docs the last blocker rather than the tooling. #3527 (closed) covered relay-side repo seeding. #2316 shows what debugging looks like when the auth half of this flow is undocumented on a stock Linux host.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.