GitHub Pages

~9 min · pages, static, docs

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Static sites without leaving GitHub

GitHub Pages serves a static site directly from a repo. With Actions, you build the site (Hugo, Jekyll, mdBook, Astro, etc.) in CI and publish via the official actions/deploy-pages action.

Setup

Repo Settings → Pages → Source: GitHub Actions.
Workflow that builds the site, uploads it as a Pages artifact, then deploys.
Optional: custom domain, HTTPS.

The canonical workflow

Three actions: actions/checkout, actions/upload-pages-artifact, actions/deploy-pages. Permissions need pages: write and id-token: write.

Code

Astro / Hugo / mdBook to Pages·yaml

name: 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: '22' }
      - 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.deploy.outputs.page_url }}
    steps:
      - id: deploy
        uses: actions/deploy-pages@v4

External links

Exercise

If you have a static site repo (docs, blog, landing page), wire it to Pages with the workflow above. Verify the deploy URL appears on the Actions run and points to a live page.