Zero-Friction Docs: Deploy Static Sites to GitHub Pages with Actions

Problem

Static docs should update when the code does. GitHub Pages can deploy from a branch or from a workflow. The Actions-based path uses configure-pages, upload-pages-artifact, and deploy-pages, with explicit permissions and a concurrency group that cancels outdated deploys.

Options and trade-offs

• Deploy from a branch: the simplest setup, with limited build control. Jekyll runs by default unless you add a .nojekyll file.
• Deploy with Actions: supports any static site generator and explicit permissions and concurrency controls.
• Environment protection: require checks before the github-pages environment deploys.

My take

Use the Actions path for any project that needs a build step. Protect the deployment environment so a failing build cannot publish.

Decision lens: maintenance cost and review latency.

Example setup: a documentation site built with a JavaScript toolchain, split into a build job that uploads an artifact and a deploy job that publishes it.

Template

.github/workflows/deploy-pages.yml:

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

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v5
      - name: Build site
        run: |
          npm ci
          npm run build
      - 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

Adjust the build commands and the artifact path for your generator.

README: describe the directory layout and note that Pages should be set to deploy from GitHub Actions.

Checklist

1. Set Pages to deploy from GitHub Actions.
2. Add the workflow above and adjust it for your build.
3. Protect the github-pages environment.
4. Add .nojekyll if you deploy from a branch with a non-Jekyll generator.
5. Test the build on a pull request before merging.

Common mistakes

• Missing the pages and id-token permissions, so the deploy fails.
• No concurrency group, so an older deploy can overwrite a newer one.
• Expecting Pages to host dynamic backends. It serves static files only.

Where this doesn't apply

• Projects that need server-side rendering or a dynamic backend.

How to get involved

• Good first issue: convert a manual deploy to a Pages workflow.
• Discussion: which build steps does your docs site need in CI?

Sources (accessed 2026-10-18)

• Creating a GitHub Pages site: https://docs.github.com/articles/creating-project-pages-manually. Branch versus Actions deployment and .nojekyll.
• Pages deploy actions: the actions/deploy-pages and actions/upload-pages-artifact repositories on GitHub. Current action versions and inputs.

---