Deploy from GitHub Actions

Before you start

You need two things: a site the repository is linked to, and a key the runner can deploy with.

Link the repository to a site, once

Install the CLI on your own machine, sign in, and create the site from the project directory, naming the folder your build writes to:

curl -fsSL https://objects.subnomic.com/subnomic/cli/install.sh | bash
subnomic login
subnomic sites create blog --dir dist

That prints the site’s address and writes subnomic.json next to your code: the site’s id and the output folder, nothing secret. Commit it. It is how the pipeline knows which site to publish and which folder to upload, so the deploy step needs no arguments. Addresses are one namespace shared by every workspace, first come first served — if blog is taken, pick another.

Create a deploy key

In the console, open the workspace menu → API tokens and create a key with two scopes: sites.read and sites.deploy. That is enough to publish a preview, promote a build and roll back. It cannot create or delete a site or attach a domain. Give it an expiry if you rotate secrets on a schedule; the key is shown once.

In GitHub, add it under Settings → Secrets and variables → Actions as SUBNOMIC_TOKEN.

The workflow

Save this as .github/workflows/site.yml. Change the two build steps to whatever your project runs; everything after them stays the same.

name: Site

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read
  pull-requests: write   # only for the preview comment below

concurrency:
  group: site-${{ github.ref }}
  # A newer commit on a pull request replaces its preview; production deploys queue.
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    # A pull request from a fork gets no secrets, so it cannot deploy a preview.
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
    env:
      SUBNOMIC_TOKEN: ${{ secrets.SUBNOMIC_TOKEN }}
      SUBNOMIC_API: https://api.subnomic.com
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run build

      - name: Install the Subnomic CLI
        run: curl -fsSL https://objects.subnomic.com/subnomic/cli/install.sh | bash

      - name: Deploy
        id: deploy
        run: |
          if [ "${{ github.event_name }}" = "push" ]; then
            url=$(subnomic sites deploy --prod)
            echo "Live at $url" >> "$GITHUB_STEP_SUMMARY"
          else
            url=$(subnomic sites deploy)
            echo "Preview at $url" >> "$GITHUB_STEP_SUMMARY"
          fi
          echo "url=$url" >> "$GITHUB_OUTPUT"

      - name: Comment the preview
        if: github.event_name == 'pull_request'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh pr comment "${{ github.event.pull_request.number }}" --body "Preview: ${{ steps.deploy.outputs.url }}"

Drop the last step, and the pull-requests: write line, if you do not want a comment on the pull request. It posts a new comment for every push to the branch.

What each deploy does

• A pull request runs subnomic sites deploy. The build is uploaded as a new deployment with an address of its own, https://blog--<id>.subnomic.app/, and nothing goes live. Every push to the branch makes another one.
• A push to main runs subnomic sites deploy --prod: the same upload, then the site’s live pointer moves to the new deployment and the site’s own address is printed.
• Only what changed is uploaded. Files are hashed on the runner, and any file an earlier deployment of the site already holds is reused rather than sent again, so the second deploy of a large site uploads a handful of files.
• Only the URL goes to stdout. Progress and the “Live at” line go to stderr, which is why url=$(…) captures the address and nothing else.
• Nothing private is published by accident. .env files, .git and node_modules are never uploaded, and a folder with no index.html is refused before anything is sent.
• Any failure fails the step. The CLI exits non-zero, so a refused deploy turns the job red instead of reporting success.

A site keeps its live deployment and the ten newest ones besides it; older ones are retired, previews included. A busy pull request therefore shortens how far back production can roll, and the preview of a long-merged branch eventually stops answering.

Preview addresses are unguessable and served with noindex, but they are not private: anyone with the link can open one. To keep previews behind a sign-in, protect the site — previews are covered by the same setting. See Keeping a site private.

Roll back

Every deployment is kept whole, so rolling back moves the live pointer to one that already exists. Nothing is rebuilt or uploaded.

subnomic sites rollback                  # to the deployment before the live one
subnomic sites rollback --to <deployment id>

Run it from your machine, or keep a button for it in GitHub. Without a terminal, rollback with no --to picks the deployment immediately before the live one:

name: Roll back site

on: workflow_dispatch

jobs:
  rollback:
    runs-on: ubuntu-latest
    env:
      SUBNOMIC_TOKEN: ${{ secrets.SUBNOMIC_TOKEN }}
      SUBNOMIC_API: https://api.subnomic.com
    steps:
      - uses: actions/checkout@v7          # for subnomic.json
      - run: curl -fsSL https://objects.subnomic.com/subnomic/cli/install.sh | bash
      - run: subnomic sites rollback

The same key works: rolling back needs sites.read and sites.deploy, nothing more. Why rollback is a pointer rather than a rebuild is in Rollback should move a pointer.

When it fails

Every flag of sites deploy, rollback and the rest is in CLI; domains, redirects and headers are in Sites.