ngit-cli 3.0.0

Release overview

ngit v3 is its biggest release yet. With CI, private repositories, software releases, and plenty more, ngit, powered by GRASP, is quickly becoming a fully fledged development solution. It launches in tandem with ngit-grasp v3, GitWorkshop v4, and the new ngit-ci 0.1 as one coordinated release across the ngit family of tools. These are the changes that define the release. Read the full launch story to see how all four releases fit together; the detailed entries below record every feature, compatibility change, and fix.

• CI is here: One of the biggest gaps holding projects back from ngit is

now closed. Discover maintainer-selected coordinators, request, trigger, and stop runs, follow workflows down to individual job logs and trust evidence, and optionally require a trusted CI result before merging.

• Private repositories without surrendering identity: Clone, fetch, push,

and collaborate on GRASP-08 private repositories using scoped Nostr and Git authentication. The repository remains a signed Nostr identity instead of becoming an account owned by its server. Basic Buzz support extends clone, pull-request, and lifecycle-status workflows to Buzz repositories.

• Maintainers and repository authority: Introduce an explicit lead,

role history, and non-maintainer moderators, with clearer invitations, handovers, departures, roster changes, and historical authorization. These substantial improvements are backwards compatible for existing repositories and confirmed maintainer relationships. The one narrow breaking change is that an invited maintainer has no Git-state authority until they accept. That pending-invitation boundary is the SemVer reason for the v3 major version bump.

• Pull requests that fit real projects: Target non-default branches, build

inferred or explicit pull-request stacks, check out contributor branches on demand, record issue-resolution provenance, and merge with stronger safety checks.

• Software releases without the platform: Think GitHub Releases without

GitHub, made resilient through Blossom replication. Publish signed NIP-82 applications, releases, and assets with Zapstore-compatible metadata, then update ngit itself from its verified releases.

Additional ngit highlights

• Credential protection: Move nsec and bunker credentials out of Git

config by default and into the OS credential store, with an ngit-specific, user-only file as fallback. This reflects a changed threat model: coding agents and other tools now routinely read Git config, making inadvertent disclosure much more likely.

• Nsite and container publishing: Publish nsites and OCI container images

through Nostr and Blossom.

• Accounts and automation: Add portable local and remote signer selection,

deliberate credential export, global JSON output and repository selection, plus a versioned agent skill installer and upgrader.

• Repository addresses: Resolve path-scoped NIP-AD mappings from memorable

bare domains, with NIP-65 relay discovery when the repository announcement is not already cached.

• Everyday Git compatibility: Support guarded force pushes with

--force-with-lease, raw object IDs in refspecs, no-op pushes, Git-managed tracking refs, and installed remote helpers for additional server protocols.

• Safer upgrades and recovery: Update from exact signed NIP-82 releases,

preserve staged, unstaged, and untracked work through merges, and provide an actionable merge recipe when synchronized refs have diverged.

• Private-network access: Connect opportunistically to .onion relays and

clone URLs through Tor, and optionally trust host-installed certificate authorities for private or development infrastructure.

Added

• Bare-domain nostr:// repository URLs can resolve path-scoped NIP-AD

mappings, including protocol and SSH-key prefixes. NIP-AD mappings and the existing hint-less nostr://<npub>/<identifier> form now bootstrap missing repository announcements through the author's NIP-65 write relays.

• ngit release publish can derive its version and source commit from one

exact Git tag, so tagged CI builds need no positional arguments. Schema-1 manifests accept Zapstore-compatible local APK release_source; ngit extracts package/version, SDK, certificate, and ABI metadata from the stable Blossom snapshot and rejects conflicts with declarative assertions.

• Schema-1 release manifests can declare Zapstore-style application metadata.

Tracked local icons and screenshots publish through Blossom, while existing HTTP(S) image URLs remain direct references and are never downloaded.

• Add ngit update, ngit update --check, and exact-version selection backed

by ngit's signed repository state and trusted NIP-82 release assets. Only receipted standalone Unix installations are replaced automatically; Nix, Cargo, and unreceipted installations receive non-mutating guidance. The canonical website installer template now shares this update path.

• Release manifests can set release_notes: CHANGELOG.md to publish the

matching Keep a Changelog version section. Missing, duplicate, and empty sections fail rather than falling back to the complete changelog.

• Add ngit nsite publish <DIRECTORY> for publishing an already-built static

site as a root or named NIP-5A manifest. The command snapshots files deterministically, confirms every unique blob on every selected Blossom server with batched BUD-11 authorization, then signs and publishes the manifest with local or remote signers. Blossom servers may be supplied explicitly, read with site metadata, fallback routing, and relay hints from nsyte's .nsite/config.json, or discovered from the account's kind-10063 server list.

• Add ngit container publish <OCI_LAYOUT> for publishing verified OCI image

layouts through Blossom and repository-bound Nostr kind-30624 state. The command uploads every reachable blob, preserves existing remote tags by default, publishes through repository relays, and supports NIP-42 and structured CI output.

• Private repositories via GRASP-08: discover private repositories through

encrypted kind-10318 relay lists, then clone, fetch, push, and collaborate using NIP-42 relay authentication and repository-scoped NIP-98 Git HTTP credentials. Private repository events stay on repository relays instead of leaking through indexers, fallback relays, or account relay fanout. Copied repository URLs can also be classified as private from GRASP-08 NIP-11 metadata before discovery begins.

• Basic Buzz support: clone Buzz repositories, view pull requests and their

lifecycle status, and push new or updated pull requests and status changes through authenticated Buzz relay and Git transport. Normal branch and tag pushes are not supported, and Buzz pull-request comments cannot be viewed or published because Buzz uses kind 1 while ngit uses NIP-22 kind 1111.

• Stored accounts can be selected for one ngit command with global

--signer <npub|alias|profile-name>, or for one Git command with git -c nostr.signer=<account>, without changing the configured login. ngit account login <account> reactivates retained credentials and --alias adds a portable signer name. An explicit selector that is missing, invalid, or ambiguous fails closed.

• Add portable one-shot and export paths for both signer types:

--nsec-file reads a local key, while interoperable --nbunksec and --nbunksec-file reuse an established NIP-46 session. Secret-file targets must be small regular files and, on Unix, use mode 0400 or 0600. ngit account export-keys returns the selected account's npub plus nsec for a local signer or nbunksec for a remote signer.

• --json is now a global option for all ngit commands. Machine-readable

results are written to stdout only after command completion, diagnostics and progress stay on stderr, and mutating commands return useful event IDs and metadata. JSON output cannot be combined with interactive mode.

• Pull requests can target a non-default branch with git push -o target-branch=<branch> or ngit send --target-branch <branch>. Root PR events expose the target as an indexed b tag, and listing, viewing, updating, merging, and applied-status detection honor the immutable target; omitting the option retains default-branch behavior. ngit merge resolves an explicit target against the latest Nostr repository state, fetching the target commit without mutating tracking refs, so a stale local clone cannot merge onto old target history.
• Pull requests automatically select the unique most-advanced tip of the author's other open or draft PRs when it is in the new proposal's history and ahead of the target branch. Existing children follow later authorized parent updates after they are rebased, while stale children and ambiguous unrelated parents fail closed. git push -o base=<commit|branch|event> and ngit send --base <commit|branch|event> override inference for that publication; PR roots select their latest authorized update, specific PR-update events select their historical commit, and unique event-ID prefixes are accepted. Repeat an explicit historical base on later child updates to keep that deliberate pin instead of following the open parent lineage.
• Issue-resolution status events now identify the triggering commit and, when

attribution is unambiguous, the proposal and merge commit that caused the status change.

• Add a multi-stage Containerfile for building a minimal Alpine-based ngit image, plus a CI smoke test that builds the image and runs ngit --version.
• Add an opt-in native-tls-roots build feature that trusts certificate authorities installed on the host alongside WebPKI roots, enabling WSS connections to relays and GRASP servers using private, corporate, or development CAs.
• ngit repo --json now exposes selected_maintainer, confirmed_maintainers, invited_maintainers, lead_maintainer, and the directional maintainer_edges alongside the backward-compatible full maintainers set.
• Add ngit skill install, upgrade, and status commands plus local and global reminder opt-outs for repository-managed coding-agent guidance. Installs add a slim versioned SKILL.md and eight on-demand reference/*.md guides to both Codex and Claude discovery paths, including static-site publication with ngit nsite, and append a compact pointer only to existing AGENTS.md or CLAUDE.md files that do not already mention ngit. Installs and upgrades preserve supported symlinks, protect modified or newer copies unless forced, and create distinct guidance-only commits; non-maintainers are advised to push the commit as a pull request, while ngit init leaves installation as an explicit suggested follow-up.
• Expand --repo-relay-only to all ngit commands that publish nostr events.
• Git server clone URLs can use installed git-remote-<scheme> helpers for listing, fetching, and pushing. Installing a helper is treated as consent for signed repository announcements to invoke it, subject to Git's protocol policy; recursive nostr, internal fd, and GRASP-reserved ws/wss schemes are not delegated.
• Global --repo <REMOTE|NADDR|NOSTR-URL> argument selects the target repository for repo-scoped operations (send, issue, pr, repo, sync, and every other command that resolves a repository coordinate). Available at any command position (ngit --repo upstream issue create, ngit issue --repo upstream create, ngit issue create --repo upstream). Value is first matched against configured remote names, then parsed as an naddr, then as a nostr:// URL.
• Repo-coordinate resolution now prints a target repository: <naddr> (source: ...) diagnostic when publishing repo-scoped events, so an incorrect target is visible before the event is signed.
• Opportunistic Tor support for .onion relays and clone URLs. ngit uses an available SOCKS5 proxy from NGIT_TOR_PROXY or probes the common system Tor and Tor Browser ports (127.0.0.1:9050 and 127.0.0.1:9150). Unavailable onion entries fail immediately so they do not delay clearnet alternatives. See docs/onion.md.

Changed

• The bundled coding-agent skill is rewritten around the guides published at

https://ngit.dev. SKILL.md keeps the rules agents get wrong and points each task slice at its bundled reference, the matching guide, and ngit <command> --help; the reference files drop material the guides cover better, describe capabilities instead of choosing workflow policy, and gain a rule to preserve choices the user or repository already made. The skill now states that it documents ngit v3 and how to install or update an older host, merges reference/repo-settings.md into reference/repositories.md, and corrects the setup-ngit action tag (v3), the issue auto-resolution keywords, and the canonical ngit pr merge behaviour.

• ngit skill install and upgrade delete reference files that a later ngit

no longer bundles, resolving the same canonical symlinks as bundled files, and stage the deletion in the guidance commit. A lingering retired file is reconciled even when the skill version is already current.

• The top-level ngit merge command is now a compatibility alias for the

canonical ngit pr merge command. Both spellings create the same local no-ff merge on the PR's declared target (or repository default), share conflict handling and options, and refuse closed or already-applied PRs before changing Git state. Preparing the local merge no longer requires a maintainer identity; the later Git push enforces repository authority and publishes the Nostr applied status. Ungated JSON keeps the PR id, entity, and action (merged or conflicted) while omitting the unrequested CI projection and unpublished event.

• JSON command-result envelopes now use top-level `command_status: "ok" |

"error" instead of the ambiguous status field or ok boolean. Nested fields continue to describe domain results, so a successful ci status`