Deploying with GitHub Pages

What is GitHub Pages?

GitHub Pages is a free static site hosting service built into GitHub. It serves HTML, CSS, and JavaScript directly from a repository.

Enable GitHub Pages

1. Go to your repository Settings > Pages
2. Under Source, select Deploy from a branch
3. Choose main branch and / (root) folder
4. Click Save
5. Your site will be live at https://your-username.github.io/your-repo/

Using a Custom Build Folder

If your project builds to a dist/ folder (e.g., Vite):

1. Build your project:

npm run build

2. Under Pages settings, choose main branch and /docs folder (rename dist to docs), or use GitHub Actions for more control.

Deploy with GitHub Actions

For projects that need a build step, use a workflow:

1. Go to Settings > Pages > Source and select GitHub Actions
2. Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages
 
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install && npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v4

Custom Domain (Optional)

1. Go to Settings > Pages > Custom domain
2. Enter your domain (e.g., game.example.com)
3. Add a CNAME record in your DNS provider pointing to your-username.github.io
4. Check Enforce HTTPS

Verify

After enabling, wait a few minutes then visit your Pages URL. Check the Actions tab if the deploy fails.