ngit-relay

Nostr-permissioned Git / Relay / Blossom Service Protocol

A complete, self-hostable data solution for Nostr Git repositories.

Protocols > Platforms

Learn More Source

Why

Git began with email for collaboration. Over time, centralised platforms dominated. Nostr lets us bring software collaboration back to open protocols. Git Via Nostr connects Git and Nostr as simply as possible via NIP-34.

Protocol

A single endpoint that bundles three services:

1. Smart HTTP Git service

  • Repos live at /<npub>/<identifier>.git
  • No user auth – pushes are validated against state announced on Nostr.
  • CORS origin * allows web app access.

2. Nostr Relay

  • Accepts events related to hosted repositories.
  • Auto-creates blank repos on repository-announcement events that list this instance.

3. Blossom Service

  • Stores images, videos and misc. blobs referenced by relay events.
  • Blobs are retained for 24 h unless referenced by an accepted event.

Reference Implementation

This trio stores everything required for Git Via Nostr while remaining narrow in scope. It's stuck together with docker and nginx.

Public Instances

Distributed Vision

Users have high expectations of Git servers. GitHub is performant, reliable, and has near 100% uptime. A self-hosted Git server can't achieve that level of performance.

We can add resilience, reliability, and uptime by treating Git servers like Nostr relays if we pull and push from multiple instances simultaneously. This way, users can achieve comparable reliability and uptime, even if some of the instances they use are occasionally down or misbehaving.

This approach prevents us from centralizing around a few performant Git servers and also allows maintainers to change Git servers without requiring their users to make any configuration changes.

To make this vision a reality, we need to encourage contributors and users to clone using the `nostr://` URL with the ngit plugin installed, rather than the `https://` URL of a single ngit-relay instance.

How to Use

  1. Deploy on your VPS or self-host (see DEPLOYMENT.md in git repo).
  2. Create a local repo:
    git init
echo project > README.md
git add .
git commit -m "initial commit"
  3. Install the ngit plugin (v1.7+). curl -Ls https://ngit.dev/install.sh | bash
  4. Run ngit init and follow prompts – it will:
    • Send a Git-announcement event to your chosen ngit-relay instances.
    • Emit a Git-state event.
    • Add a nostr:// remote and push for you.

Subsequent git push operations broadcast to every server listed in the announcement. Repos are cloned via nostr:// for resilience and decentralisation.

Features / Roadmap

Done

  • Smart HTTP Git server
  • Pre-receive hook (NIP-34)
  • Multi-maintainer support
  • Nostr relay with provisioning hook
  • Blossom server
  • Proactive git sync

Planned

  • Blossom retention policy enforcement
  • Proactive Nostr & Blossom sync
  • Spam prevention
  • Instance-discovery announcements
  • Repo whitelist & Auth-to-read options
  • Archive service for orphaned repos

FAQ

When Private Repos?

Add auth-to-read using NIP-42 plus a whitelist and run behind a firewall. For truly sensitive work, combine with protected-event support (NIP-70).

Why use multiple ngit-relay instances?

High availability comes from pushing & pulling across many relays simultaneously, giving GitHub-level uptime without centralisation.

Why is this a Protocol?

So tools can be built on top of it for a silky smooth Git via Nostr experience.

Further Information

More details in README.md in git repo

long-form nostr article Vision for #GitViaNostr by DanConwayDev