ngit docs

Publish an nsite ​

Publish an already-built static website to Blossom, then announce its files as a signed NIP-5A nsite. The site is identified by its publishing key rather than tied to one web host; named sites add an identifier beneath that key.

Choose the publisher ​

nsyte is the dedicated nsite CLI and the best place to start when managing nsites directly. It provides the broader, more advanced set of nsite setup, management, and publication options.

ngit nsite publish is a focused publisher rather than a replacement for all of nsyte. It exists so repository automation can install one tool and use ngit's account and signer machinery for both ngit release publish and nsite publication. The two publications may still use different identities. This is especially useful when a CI job builds both downloadable releases and a static site.

ngit reads nsyte's JSON .nsite/config.json, so an existing project can often replace:

bash
nsyte deploy dist

with:

bash
ngit nsite publish dist --json

Use nsyte when you need its complete nsite workflow. Use ngit when the site is one output of a repository or release pipeline and its supported publication controls are enough.

Publish a built site ​

Pass the build output, not the source directory. ngit does not run the build or apply ignore files; it publishes every regular file in the directory. Symlinks, unsafe paths, and filenames without extensions are rejected.

With an existing ngit account, the shortest publication is:

bash
ngit nsite publish dist --title "Example documentation" --json

By default, ngit reads .nsite/config.json, discovers the active account's Blossom servers, and publishes a root site. A named site, explicit publication targets, or a single-page-app fallback can be selected with command options:

bash
ngit nsite publish dist \
  --id docs \
  --fallback index.html \
  --blossom-server https://blossom.example.com \
  --relay wss://relay.example.com \
  --json

Explicit --blossom-server or --relay values replace the corresponding configuration array. For all supported metadata, configuration fields, replication behaviour, and JSON results, use the generated ngit nsite publish reference.

Preview every pull request ​

A PR preview does not need the production site's identity. Create a fresh local account inside the job, publish the checked build with that disposable key, and expose the gateway URL as a job output:

yaml
name: Preview

on:
  pull_request:

jobs:
  preview:
    runs-on: ubuntu-latest
    outputs:
      nsite_preview: ${{ steps.preview.outputs.url }}
    steps:
      - uses: actions/checkout@v4
      - uses: danconwaydev/setup-ngit@v3
      - run: npm run build
      - name: Create a disposable identity
        run: |
          ngit account create \
            --name "PR preview" \
            --offline \
            --local \
            --secret-storage file \
            --json
      - name: Publish the checked build
        run: |
          ngit nsite publish dist \
            --no-config \
            --blossom-server https://blossom.example.com \
            --relay wss://relay.example.com \
            --defaults \
            --json
      - id: preview
        env:
          NSITE_PREVIEW_URL: https://replace-with-the-published-preview.example
        run: printf 'url=%s\n' "$NSITE_PREVIEW_URL" >> "$GITHUB_OUTPUT"

Replace the build command, publication targets, and gateway URL with those for your site. Set the output only after both publication and any availability check succeed.

An output named nsite or beginning with nsite_ is the standard nsite preview convention. GitWorkshop recognises it on the public Nostr Job Result and shows an Open nsite preview action on the PR. The signed CI result connects the commit to the disposable identity without giving contributor-controlled code a maintainer key.

Output values are public, so never put a credential in one. See Public outputs and PR previews for the exact output rules, omission behaviour, size limits, and trust warning. Use a long-lived maintainer-authorised signer only for production publication.

Next ​