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 <relay>/git/<owner-pubkey>/<repo-id> |
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.
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):buzz repos createpublishes the kind:30617 announcement--help--channelbinding is the git ACL; without it clone/fetch/push fail--help+ code comments (crates/buzz-cli/src/commands/repos.rs:221— "the tag is the git ACL")<relay>/git/<owner-pubkey>/<repo-id>desktop/src/features/projects/lib/projectCloneUrl.tscommentsdesktop/src-tauri/src/managed_agents/nest_skill.mdcrates/git-credential-nostr/README.mdget_member_roleagainst the bound channel,Bot → Member)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 withmaintainerstags,buzz-protectpush-allowed lists, and NIP-OA owner inheritance — but the implemented gate is channel-membership resolution against thebuzz-channelbinding. 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
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.Additional context
Related issues (searched open and closed): #2877 and #3539 documented the era when shipped clients couldn't emit the
buzz-channeltag 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.