Amber/.agents/skills/ngit/SKILL.md

name, description, license, metadata

name	description	license	metadata
ngit	Commands and workflows for NIP-34 git collaboration over Nostr with the ngit CLI and git-remote-nostr. Use in any repository with a nostr:// remote for generic collaboration requests (open an Issue, create or review a Pull Request (PR), comment, merge, clone) and whenever a task involves nostr:// URLs, ngit commands, Grasp servers, gitworkshop.dev, Nostr CI status and workflows, software releases and Zapstore publication, OCI container images, or nsite static sites published through Blossom.	CC-BY-SA-4.0	version 1.18

ngit — Nostr Plugin for Git

ngit makes git clone, fetch, and push work with nostr:// URLs and adds a CLI for pull requests, issues, membership, CI results, releases, OCI containers, and nsites. Repository state (which commit each ref points to) is published as signed Nostr events and is the source of truth; git objects live on ordinary git servers, so servers are interchangeable. A grasp server bundles a relay and a git server and creates the repository automatically when an announcement lists it. Explanation: https://ngit.dev/how-it-works

Where to look

• This skill documents ngit v3. Run ngit --version first; the commands here need 3.0.0 or later. If ngit is missing or older, report that and offer an install or update: curl -fsSL https://ngit.dev/install.sh | bash installs or replaces ngit and git-remote-nostr, and ngit update works on v3 or later. Other methods: https://ngit.dev/install
• ngit <command> --help is the authority for the installed version's flags and defaults.
• https://ngit.dev holds the guides. Any page is available as raw Markdown at https://ngit.dev/markdown/<route>.md; the index is https://ngit.dev/llms.txt. Web UI: https://gitworkshop.dev

Rules

• Preserve user and repository choices. Examples here show syntax, not policy. Carry through the selected signer, target, hosting, CI, and replication settings; do not add gates, waits, workflow edits, or configuration changes that the task or repository did not choose.
• PR branches MUST start with pr/ (e.g. pr/my-feature). Any other branch name is a plain push and never creates a PR.
• Read ngit output with --json. It is a global option and works at any position. Stdout is exactly one JSON document; progress and diagnostics go to stderr. git commands have no --json. Top-level command_status is ok for exit 0 and error otherwise; it never describes a nested domain result (ngit ci status --json reports ok with ci.conclusion: "failure" unless a gate was requested).
• Add --offline after the first network read in a session, on commands that support it. git fetch origin also refreshes the cache.
• Identifiers. <ID|nevent> accepts nevent1…, a 64-char hex ID, or a unique hex prefix with an optional # (quote it: '#deadbeef'). JSON id and reply_to fields are already nevent1…; container publication instead returns a raw-hex event_id plus the repository naddr. Reference events inside --body text as nostr:nevent1… or nostr:naddr1…, never as raw hex. Never construct a NIP-05 address (user@domain); use npub1… unless a NIP-05 address was given to you.
• Multiline text. ngit options such as --body and --description accept real newlines: --body "$(cat note.md)". Git push options cannot carry newlines: write literal \n in a short inline -o description=…, and never convert a file into a push option (open the PR with ngit send instead).
• Signers. --signer <alias|npub|profile-name> selects a stored identity for one ngit command; git -c nostr.signer=<alias|npub|profile-name> push … does the same for one git command. Neither changes the configured login. Never export or pass an nsec merely to switch between configured accounts.
• CI. A successful push says nothing about CI. Nostr CI runs workflows from .ngit/act/workflows/; another provider's directory is not evidence. When CI matters, query the exact commit or PR with ngit ci status <target> --json and read ci.state and ci.conclusion, not command_status.
• Target repository. With several nostr:// remotes, pass global --repo <REMOTE|NADDR|NOSTR-URL>; a configured remote name, an naddr, and a nostr:// URL are all accepted. Without it ngit infers the target from config and branch tracking and fails rather than guesses. Before a signing command, check the target repository: <naddr> (source: …) line on stderr.

Detecting a nostr repo

git remote -v | grep -q 'nostr://'   # primary check, no cache needed
ngit repo --json --offline            # full metadata when needed

ngit repo always exits 0, and is_nostr_repo: false can be a cold-cache false negative: if a remote shows nostr://, run git fetch origin and retry. The output includes the roster (members, lead_source, lead_path, pending_actions, health); read reference/repositories.md before changing membership or hosting.

nostr:// URLs

nostr://<npub>/<identifier>
nostr://<npub>/<relay-hint>/<identifier>   # relay-hint is a bare domain, e.g. relay.ngit.dev
nostr://<user>@<domain>/<identifier>       # NIP-05, only when explicitly provided
nostr://<domain>/<repository-path>         # NIP-AD: the full /path is sent URL-encoded to /.well-known/nostr.json?path=

Standard git commands accept these URLs directly.

Task index

Read the bundled reference before performing that slice of work; the guide adds tutorials and background.

Task	Bundled reference	ngit.dev guide
Publish, clone, host repositories; maintainers, moderators	reference/repositories.md	/repositories, /maintainers
Open, update, stack, review, merge PRs	reference/prs.md	/pull-requests
Issues	reference/issues.md	/issues
CI results, trust, workflows, ngit in CI jobs	reference/ci.md	/ci, /ci/workflows/
Accounts, login, signers, secrets	reference/accounts.md	/accounts
Sync, global flags, git config	reference/sync-config.md	/configuration, /troubleshooting
Publish nsites (static sites)	reference/nsites.md	/releases/nsites
Publish OCI containers	reference/containers.md	/releases
Software releases	ngit release --help	/releases
Automation contract, machine-readable docs	this file	/agents/