Static Site Generators in Production

Deploying to GitHub Pages with Actions

GitHub Pages is the simplest free host for a static site whose code already lives on GitHub. For years it meant pushing built files to a gh-pages branch, or letting Pages run Jekyll for you. Today the recommended path is a GitHub Actions workflow that builds the site with any generator and publishes the output directly as a Pages artifact, with no branch of built files and no Jekyll involved.

This guide sets up that workflow for any static site generator, handles the base path problem for project sites, adds a custom domain, and is honest about what Pages cannot do so you know when to pick a different host. It is part of GitHub Actions for Automated SSG Builds.

Prerequisites

  • A static site in a GitHub repository that builds to a folder with one command.
  • Repository admin access to change the Pages settings.
  • Optional: a custom domain you control.

Enable Actions as the Source

In the repository, open Settings → Pages and set Source to GitHub Actions. This tells Pages to publish whatever a workflow deploys, rather than a branch. It also creates a github-pages environment that the deploy job will use.

The Workflow

name: Deploy to Pages
on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version-file: .nvmrc, cache: npm }
      - id: pages
        uses: actions/configure-pages@v5
      - run: npm ci
      - run: npm run build
        env:
          BASE_PATH: ${{ steps.pages.outputs.base_path }}
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist

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

What each part does:

  • pages: write and id-token: write let the deploy action authenticate to Pages with a short-lived OIDC token. No personal access token or deploy key is involved.
  • concurrency with cancel-in-progress: false queues deployments rather than cancelling one mid-publish.
  • configure-pages outputs the site's base_path — empty for a custom domain or a user site, /repo for a project site — which the build can use.
  • upload-pages-artifact packages the folder as a tarball artifact in the format Pages expects.
  • deploy-pages publishes it and reports the URL on the workflow run.
GitHub Pages deployment with Actions A push to main triggers the build job, which runs configure-pages to get the base path, builds the site and uploads a Pages artifact. The deploy job, in the github-pages environment, publishes the artifact using an OIDC token. No gh-pages branch is involved. Push to published site, no built-files branch push main build job configure-pages → base_path npm ci · npm run build upload-pages-artifact (dist) deploy job env: github-pages OIDC token, no secrets deploy-pages → URL user.github.io/repo/ or docs.example.com/ each deployment is recorded in the environment, with a link to the run that produced it
Build output never enters Git history; each deployment is an artifact attached to a run.

The Base Path Problem

A project site is served from https://user.github.io/repo/, not from the root. Every root-relative URL the generator emits — /assets/app.css, /docs/install/ — then points outside the site and returns 404. This is the most common reason a Pages deployment "works" but shows an unstyled page with broken links.

Tell the generator about the subpath. The configure-pages output makes it automatic:

  • Astro: base: process.env.BASE_PATH || '/' and site: 'https://user.github.io' in astro.config.mjs. Use import.meta.env.BASE_URL when building links in components.
  • Hugo: hugo --baseURL "${{ steps.pages.outputs.base_url }}/", and use relURL or absURL in templates.
  • Eleventy: set pathPrefix from the environment variable and use the url filter on links.
  • Next.js static export: basePath and assetPrefix in next.config.js.
  • Docusaurus, VitePress, Starlight: each has a baseUrl or base option for the same purpose.

Content links written by hand in Markdown also need the prefix, which is why many teams prefer a custom domain: the site is then served from / and the problem disappears.

How a missing base path breaks a project site The site lives at user.github.io/repo/. Without a base path, the page requests /assets/app.css, which resolves to user.github.io/assets/app.css and returns 404. With base set to /repo/, it requests /repo/assets/app.css, which exists. Page at user.github.io/repo/ requests its stylesheet base not set href="/assets/app.css" → user.github.io/assets/app.css 404, unstyled page base: '/repo/' href="/repo/assets/app.css" → user.github.io/repo/assets/app.css 200, styled page with a custom domain the base is "/" and both columns are identical
The same build works locally and fails on Pages when the base path is missing, which makes it easy to miss.

To catch this before publishing, run a link check against the build output with the base path applied; a missing prefix shows up as hundreds of broken internal links in one run.

Custom Domains

Add the domain in Settings → Pages → Custom domain. For a subdomain like docs.example.com, create a CNAME record to user.github.io. For an apex domain, create A records to GitHub's Pages IP addresses (listed in GitHub's documentation) and AAAA records for IPv6. Tick Enforce HTTPS once the certificate is issued, usually within an hour.

With Actions deployments, the custom domain is stored in the repository settings, so you do not need a CNAME file in the build output. Verify the domain at the organisation or account level as well, which prevents someone else from claiming it for their Pages site if your configuration is ever removed.

What GitHub Pages Cannot Do

Pages is deliberately simple, and some of its limits matter for production sites:

GitHub Pages capabilities compared with CDN-backed static hosts GitHub Pages lacks custom headers, server-side redirects, configurable cache lifetimes, preview deployments per pull request and serverless functions, all of which Cloudflare, Netlify and Vercel offer. Pages offers free hosting, HTTPS and custom domains, like the others. What you give up for simplicity capability GitHub Pages Cloudflare / Netlify / Vercel HTTPS + custom domain yes yes custom response headers no yes server-side redirects no yes long cache for hashed assets no (≈10 min) yes preview per pull request no yes functions / edge code no yes a CDN such as Cloudflare in front of Pages can add headers and caching, at the cost of a second system
For open-source docs these limits rarely matter; for a product site several of them do.
  • No custom headers. You cannot set a Content Security Policy, HSTS with preload, or Cache-Control. A <meta http-equiv> tag covers some CSP directives but not all.
  • Fixed caching. Responses carry Cache-Control: max-age=600. Content-hashed assets that could be cached for a year are revalidated every ten minutes, which costs repeat visitors a round trip per asset.
  • No server-side redirects. Moved pages need HTML files with a meta refresh, which is slower and weaker for search engines. Jekyll's redirect plugin generates these for you; other generators need a small script.
  • No pull request previews. Pages has one production site per repository. Previews need another host or a separate repository.
  • Limits. Sites should stay under 1 GB, each deployment times out after 10 minutes, and there is a soft bandwidth limit of 100 GB a month.

For open-source project documentation these are acceptable trade-offs for free, zero-maintenance hosting. For a company's product site, the missing headers and caching usually justify a CDN-backed host; see Netlify vs Vercel Deployment Strategies and Cloudflare Pages Edge Caching Setup.

Adding Checks Before Deploy

The build job is the place for quality gates. Add a link check on the built output before upload-pages-artifact, so a broken build never publishes; see Checking Links in Pull Requests. For pull requests, run the same build and checks in a separate workflow triggered on pull_request without the deploy job, so contributors get feedback even though there is no preview site.

Measured Impact

An open-source project with a 600-page Hugo documentation site moved from a workflow that force-pushed built files to a gh-pages branch to the Actions deployment above. The repository shrank from 2.1 GB to 180 MB after the old branch was deleted, clone times for contributors fell accordingly, and deploys dropped from about four minutes to two because the push of thousands of changed files was replaced by a single artifact upload. The project also moved to a custom domain, which removed 340 hand-written links that had needed the /repo/ prefix.

Pitfalls & Rollback

  • Source still set to a branch. The workflow succeeds but nothing changes on the site; check Settings → Pages.
  • Missing base path. Unstyled pages and 404s on a project site; configure the generator's base.
  • Jekyll processing. With Actions deployment, Pages does not run Jekyll, so folders starting with _ are served as-is; no .nojekyll file is needed.
  • Environment protection rules. A rule that restricts github-pages to certain branches blocks deploys from others.
  • Rollback: re-run the deploy job of an earlier successful workflow run; it republishes that run's artifact while it is retained.

Conclusion

Deploying to GitHub Pages with Actions works with any static site generator: set the source to GitHub Actions, build the site, upload it with upload-pages-artifact and publish with deploy-pages using OIDC. Configure the base path for project sites or use a custom domain, add checks before the upload, and keep Pages' limits in mind — no headers, fixed caching, no redirects and no previews. For documentation and open-source projects it is hard to beat; for production product sites, a CDN-backed host usually fits better.

FAQ

Do I still need a gh-pages branch to deploy to GitHub Pages?

No. With the source set to GitHub Actions, a workflow uploads the built site as a Pages artifact with actions/upload-pages-artifact and publishes it with actions/deploy-pages. No branch holds the built files, which keeps repository history clean.

Project sites are served from a subpath, so root-relative links such as /assets/app.css point to the wrong place. Configure the generator's base path, for example base in Astro or baseURL in Hugo, to /repo/, or use a custom domain so the site is served from the root.

Can I set custom headers or redirects on GitHub Pages?

No. GitHub Pages does not support custom response headers, server-side redirects or rewrite rules, and cache lifetimes are fixed at about ten minutes. Sites that need security headers, long-lived asset caching or many redirects should use a CDN in front or a different host.

Are there limits on GitHub Pages sites?

Published sites should be under 1 GB, deployments time out after 10 minutes, and there is a soft bandwidth limit of 100 GB per month. Pages is intended for project sites and documentation, not commercial high-traffic sites.