Deploy with GitHub Pages

Recipe for publishing a folder2website site with GitHub Pages and a custom domain.

Replace:

• OWNER with your GitHub owner.
• REPO with your repo name.
• DOMAIN with your custom domain.

Workflow#

Create .github/workflows/pages.yml:

name: Deploy GitHub 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: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun index.ts . --out site --base-url https://DOMAIN
      - run: printf 'DOMAIN\n' > site/CNAME
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: site

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

GitHub#

Enable Pages from Actions:

gh api repos/OWNER/REPO/pages -X POST -f build_type=workflow

If Pages already exists:

gh api repos/OWNER/REPO/pages -X PUT -f build_type=workflow

Set the custom domain:

gh api repos/OWNER/REPO/pages -X PUT -f cname=DOMAIN

DNS#

Add a CNAME at your DNS provider:

DOMAIN -> OWNER.github.io.

Example for this repo:

folder2website.tangerinetech.eu -> spashii.github.io.

Verify:

dig +short DOMAIN CNAME

Best practices#

• Deploy with Pages Actions, not a committed site/ directory.
• Always pass --base-url https://DOMAIN for production builds.
• Write site/CNAME in the workflow. Do not rely on local files being present.
• Use a CNAME for subdomains: docs.example.com -> OWNER.github.io..
• Keep deploy output outside the source tree during local tests.
• Check DNS before debugging GitHub Pages.
• Wait for GitHub’s certificate before enforcing HTTPS.
• Keep the workflow boring: checkout, setup Bun, install, build, upload, deploy.

Deploy#

Push to main, or run:

gh workflow run pages.yml

Check status:

gh run list --workflow pages.yml
gh api repos/OWNER/REPO/pages