Platform target

GitHub Pages

GitHub Pages needs no special Nift output format. The target deliberately keeps the ordinary public/ artifact; a GitHub Actions workflow builds and deploys that directory.

Create and build

nift init --target=github-pages
nift build --all
nift status

What Nift creates

The project is the normal HTML starter with public/ as its output directory. No provider file is invented because Pages can deploy an arbitrary static artifact from a custom Actions workflow.

Deployment workflow

A complete workflow has four responsibilities: obtain the intended Nift version, build the site, upload exactly public/, and deploy the Pages artifact.

name: Deploy Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install the reviewed Nift release
        shell: bash
        run: |
          curl -fsSL https://nift.dev/install |
            NIFT_VERSION=4.0.7 NIFT_INSTALL_DIR="$RUNNER_TEMP/nift-bin" sh
          echo "$RUNNER_TEMP/nift-bin" >> "$GITHUB_PATH"

      - name: Build
        run: |
          nift version
          nift build --all
          nift status

      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v4
        with:
          path: public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    permissions:
      pages: write
      id-token: write
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

The example pins the Nift product version but uses readable action major tags. For a protected production workflow, replace third-party action tags with reviewed full commit SHAs and use your dependency-update process to advance them deliberately.

Enable Pages

1. In repository settings, choose GitHub Actions as the Pages source.
2. Push the workflow and inspect the build job before approving any protected environment.
3. Confirm the deployment URL and open nested pages/assets, not only the homepage.
4. Keep the workflow's Nift version aligned with the version expected by the repository.

Account sites, project sites and paths

Use @path for Nift-managed local pages and assets so links remain output-relative. Audit handwritten root-relative URLs, client-router base paths, web manifests and runtime fetch calls separately.

Custom domains and HTTPS

Add the domain in Pages settings, configure the DNS records GitHub provides, then enable HTTPS after the certificate is ready. Preserve the generated deployment's domain association according to the Pages workflow/settings model; if your process requires a CNAME file in the artifact, ensure it reaches the root of public/ on every build rather than editing a generated copy once.

Runtime and header boundaries

GitHub Pages is static hosting. It does not run your backend and does not provide the same repository-defined response-header controls as platforms with a headers configuration file. Host runtime APIs elsewhere and call them over HTTPS. If the project requires strict custom response headers, edge middleware or server routing, choose a host that explicitly provides those controls.

Caching

Use content-hashed filenames for browser assets that need aggressive long-lived caching, and update the checked reference when the filename changes. You cannot rely on application-server cache logic on Pages, so verify the response behavior delivered by the platform and design stable filenames conservatively.

Troubleshooting

Official references: custom workflows, Pages overview, custom domains, and limits.