ngit docs

GRASP-01: Core service requirements ​

Nostr Relay ​

MUST serve a NIP-01 compliant nostr relay at / that accepts git repository announcements and their corresponding repo state announcements.

MUST reject git repository announcements that do not list the service in both clone and relays tags unless implementing GRASP-05.

MAY reject git repository announcements based on other criteria such as pre-payment, quotas, WoT, whitelist, SPAM prevention, etc.

MUST accept other events that tag, or are tagged by, either:

  1. accepted git repository announcements; or
  2. accepted issues or patches

MAY reject or delete events for generic SPAM prevention reasons or curation eg. WoT, whitelist, user bans and banned topics.

Purgatory ​

Accepted git repository announcements, repo state announcements, PRs and PR Updates SHOULD be accepted with message "purgatory: won't be served until git data arrives" and kept in purgatory (not served) until the related git data arrives and otherwise discarded after 30 minutes.

NIP-11 ​

MUST serve a NIP-11 document:

  1. MUST list each supported GRASP under supported_grasps in format GRASP-XX eg GRASP-01 as a string array
  2. MUST list repository acceptance criteria under repo_acceptance_criteria as a human readable string
  3. MUST list brief summary of curation policy under curation if events are curated beyond generic SPAM prevention; otherwise curation MUST be ommitted

Git Smart HTTP Service ​

MUST serve a git repository via an unauthenticated git smart http service at /<npub>/<percent-encoded-identifier>.git for each accepted git repository announcement.

MUST accept pushes via this service that match the latest repo state announcement on the relay, respecting the recursive maintainer set.

MUST set repository HEAD per repo state announcement as soon as the git data related to that branch has been received.

MUST accept pushes via this service to refs/nostr/<event-id> but SHOULD reject if event exists on relay listing a different tip and MAY reject based on criteria such as size, SPAM prevention, etc. SHOULD delete and MAY garbage collect these refs if no corresponding git PR event or git PR update event, with a c tag that matches the ref tip, is accepted by relay with 20 minutes.

MUST include allow-reachable-sha1-in-want, allow-tip-sha1-in-want, and filter in advertisement, serve available oids, and permit blob:none and tree:0 filters.

SHOULD serve a webpage at the same endpoint linking to git nostr client(s) to browse the repository and a 404 page for repositories it doesn't host.

CORS Support ​

To enable cross-origin access for web-based Git clients, implementations MUST support the following CORS configuration:

  1. Set Access-Control-Allow-Origin: * on ALL responses
  2. Set Access-Control-Allow-Methods: GET, POST on ALL responses
  3. Set Access-Control-Allow-Headers: Content-Type on ALL responses
  4. Respond to OPTIONS requests with 204 No Content