Code sites

What a code site is

Your repository builds a static export: next.config with output: 'export', or any tool that writes an index.html at the root of a folder. nertia hosts that folder behind the same preview, door, domain and Members card as any site. nertia never writes to your repository: your own GitHub Action builds the site, and nertia only stores and serves what it builds. A filename containing a literal percent sign is served only at its encoded URL, so avoid % in filenames.

Set up, once

1. An admin creates the site in the admin console with its address and the repository (for example example-org/demo-site).
2. Connect the Nertia app to the repository from the site's Settings. The steps are under Connect with the Nertia app below.
3. Add the workflow file from that section as .github/workflows/nertia-publish.yml. It needs no secret and no variable.

If the app can't be installed on the repository, publish with a token instead, as Use a token instead below describes.

Publish

Push to the default branch. The Action builds the site, and the site's preview at your-site.nertia.ai shows the new release a few minutes later. Check it there, then press Put the preview live on the site's Overview, or call publish_site with production from the connector. With the Nertia app connected, every finished run of the workflow, failed ones included, shows under Builds on GitHub on Overview with a link to the run. Without it, a build failure stays in your repository's Actions tab.

Overview lists every release with its commit, newest first. Roll back to this puts an earlier release live again, and Take offline shows coming soon on every live address until you put the site back online.

From Claude

Edit the repository with GitHub's own tools: the GitHub connector in claude.ai, or Claude Code. The nertia connector never edits code. On a code site it reads the site and its releases (get_site), publishes (publish_from_github, or publish_site with staging), puts live (publish_site with production), rolls back (rollback_release) and takes the site offline and back (take_offline, put_back_online). Every other site tool answers that the site is built from its repository.

publish_from_github starts your workflow from nertia. It needs the site connected to GitHub: through the Nertia app (below), or with a dispatch token as the fallback. The Changed since the live release list on Overview reads through the same connection. Without either, push to the default branch or press Run workflow on GitHub.

Connect with the Nertia app

The app is how a code site publishes with no nertia secret in your repository. It adds Publish from GitHub on Overview, publish_from_github from the connector, preview rebuilds without a new commit, and the Builds on GitHub list. There is no token to make, copy or renew.

1. On the site's Settings, press Connect GitHub.
2. GitHub opens the Nertia app's install page. Pick the account that owns the repository, choose Only select repositories and pick the site's repository (for example example-org/demo-site). The app asks for Actions read and write, Contents read and Metadata read, and nothing else.
3. GitHub asks you to sign in to the Nertia app once, so nertia can check that you can reach that repository yourself. Then it sends you back to Settings, which shows Connected through the Nertia app with the installation and the date.
4. Add this workflow file as .github/workflows/nertia-publish.yml. Once the app is connected, the site's Settings offers the same file with your default branch filled in.

# .github/workflows/nertia-publish.yml
# No secrets: when a run passes, the Nertia GitHub app publishes the nertia-site artifact.
name: Publish to nertia
on:
  push: { branches: [main] }
  workflow_dispatch: { inputs: { ref: { description: 'ref to build', required: false } } }
permissions: { contents: read }
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with: { ref: '${{ inputs.ref || github.ref }}' }
      - uses: actions/setup-node@v5
        with: { node-version: 22, cache: npm }
      - run: npm ci && npm run build && test -f out/index.html
      - uses: actions/upload-artifact@v4
        with: { name: nertia-site, path: out, retention-days: 3, if-no-files-found: error }

The workflow builds the site and keeps the out folder as the run's artifact, named nertia-site. When the run passes, GitHub tells the Nertia app, and nertia downloads that artifact and publishes it to the preview, with the same limits as below. Each run publishes once, even if GitHub reports it twice. If the run passed but uploaded no nertia-site artifact, or the build breaks a limit, nothing is published and the site's history says why.

While the app is connected, nertia refuses uploads made with a publish token, so a run can't publish twice. If you set the site up with a token first, switch to the workflow above, then delete the NERTIA_PUBLISH_TOKEN secret from the repository and revoke the token on Settings once the first build from the app shows up.

If you can't install apps on the account, GitHub sends the request to an owner instead. Once they approve it, press Connect GitHub again.

Disconnect on Settings makes nertia stop using the app for this site. It doesn't uninstall the app on GitHub: to remove it there, open the account's Settings, then Applications. Uninstalling the app on GitHub, or taking the repository away from it, disconnects the site here on its own. A disconnected site publishes with a token again: see below.

Use a token instead

The fallback, for a repository the app can't be installed on. Without the app, the workflow uploads the build itself with a publish token, and nertia starts the workflow with a dispatch token.

Upload with a publish token

1. On the site's Settings, press Mint a publish token. It is shown once: store it in the repository as the secret NERTIA_PUBLISH_TOKEN. Minting a new token revokes the old one.
2. Add the repository variable NERTIA_SITE with the site's address (for example your-site).
3. Add the workflow file below as .github/workflows/nertia-publish.yml. Without the app, the site's Settings offers the same file with its own address filled in.

# .github/workflows/nertia-publish.yml
# Repository variable:
# NERTIA_SITE = your-site
# Repository secret: NERTIA_PUBLISH_TOKEN (mint it on the site Settings)
name: Publish to nertia
on:
  push: { branches: [main] }
  workflow_dispatch: { inputs: { ref: { description: 'ref to build', required: false } } }
permissions: { contents: read }
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with: { ref: '${{ inputs.ref || github.ref }}' }
      - uses: actions/setup-node@v5
        with: { node-version: 22, cache: npm }
      - run: npm ci && npm run build && test -f out/index.html
      - run: npx @nersh/publish out --site ${{ vars.NERTIA_SITE }}
        env:
          NERTIA_PUBLISH_TOKEN: ${{ secrets.NERTIA_PUBLISH_TOKEN }}

Start builds with a dispatch token

A fine-grained personal access token scoped to that one repository, with Actions read and write and Contents read. It sits under Use a token instead on the site's Settings. When the app and a token are both set, nertia uses the app.

1. Open a new fine-grained token on GitHub.
2. Set Resource owner to the repository's owner (for example example-org). Under Repository access, choose Only select repositories and pick the site's repository (for example example-org/demo-site).
3. Under Permissions, give Actions read and write and Contents read. Nothing else.
4. Choose an expiry. When the token expires, Publish from GitHub stops with GitHub's refusal until you replace the token.
5. Generate the token, copy it, and paste it into Dispatch token under Use a token instead on the site's Settings. Once stored it shows only as Stored: Replace takes a new one and Remove deletes it.

Limits

• 64 MB in all, 2,000 files, 16 MB per file. Over a limit, the upload answers with the sizes, and the app writes them to the site's history.
• Static files only. Accepted types: .html, .css, .js, .mjs, .json, .map, .txt, .xml, .webmanifest, .svg, .png, .jpg, .jpeg, .webp, .avif, .gif, .ico, .woff, .woff2, .ttf, .otf, .mp4, .webm, .pdf.
• No server code: API routes, server actions and middleware do not run.
• Paths under /api/ belong to nertia on every site address.
• robots.txt and sitemap.xml are nertia's for now; your own copies are not served.

Analytics

nertia adds nothing to your pages. To count page views, add the beacon line from the site's Settings to your layout:

<script>navigator.sendBeacon('/api/analytics/hit',JSON.stringify({slug:'your-site',path:location.pathname}))</script>

The counts show on the site's Analytics.

From a laptop

For a site without the app, with its publish token:

NERTIA_PUBLISH_TOKEN=... npx @nersh/publish out --site your-site --repo example-org/demo-site --commit $(git rev-parse HEAD) --ref main

The upload lands on the preview, exactly as from the Action. It never puts the site live. A site connected through the app publishes from its workflow runs only.