Deploy to GitHub Pages
Automate static site deployment with GitHub Actions — build, publish, and get a live URL on every push to main
Skills taught: cicd.github-pages, cicd.deploy-pages, cicd.static-deploy, cicd.environment-urls
GitHub Pages — the easiest deployment target
GitHub Pages serves static files (HTML, CSS, JS) directly from your repository — for free. Combined with GitHub Actions, every push to main automatically builds your site and publishes the new version. It's how KERNAL itself deploys. No server, no hosting bill, no manual uploads.
The modern Pages workflow
name: Deploy to GitHub Pages
on:
push:
branches: [main]
# Required permissions for Pages deployment
permissions:
contents: read
pages: write
id-token: write
# Only one deployment at a time — cancel pending if new push arrives
concurrency:
group: pages
cancel-in-progress: false # false: don't cancel in-progress deploys
jobs:
# ── Job 1: Build ──────────────────────────────────────
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20', cache: 'npm' }
- run: npm ci
# Configure Pages (sets BASE_URL for Vite/CRA/etc.)
- name: Setup Pages
uses: actions/configure-pages@v5
- name: Build
run: npm run build
# Most frameworks read GITHUB_PAGES env var and adjust base path
# For Vite: set base in vite.config.ts → base: '/repo-name/'
# Upload the built files as a Pages artifact
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./dist # your build output folder
# ── Job 2: Deploy (separate job for security) ─────────
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }} # live URL in workflow UI
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
Custom domain setup
# Option 1: CNAME file in your repo root (or /public for React/Vite)
# Create a file named CNAME with just your domain:
# mysite.com
# Vite project: put CNAME in /public/ so it's copied to dist/
# Create: public/CNAME with content:
# kernal.dhurta.org
# Then in your domain DNS:
# CNAME kernal prashantkeshr.github.io.
# Or for apex domain:
# A @ 185.199.108.153
# A @ 185.199.109.153
# A @ 185.199.110.153
# A @ 185.199.111.153
# Option 2: Set in workflow:
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./dist
# In GitHub Settings → Pages → Custom domain
# GitHub handles the HTTPS certificate automatically (Let's Encrypt)
Vite base path for project pages
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
// Without a custom domain, GitHub Pages serves your site at:
// https://username.github.io/repository-name/
// Vite needs to know the subpath to correctly resolve assets:
base: process.env.CI ? '/repository-name/' : '/'
// With a custom domain (kernal.dhurta.org), use base: '/'
})
Tip: Enable Pages before the first deploy. Go to your repository Settings → Pages → Source → select 'GitHub Actions' (not a branch). If you leave it on 'Deploy from a branch' the Actions workflow will conflict with the old deployment method. You only need to do this once per repository.
Frequently Asked Questions
Can I deploy a backend/API alongside the frontend on GitHub Pages?
No — GitHub Pages serves only static files. For APIs, you need a separate backend host: Railway, Fly.io, Render, or a VPS. The frontend on Pages makes HTTP calls to the API hosted elsewhere. This separation is common and works well — your frontend deployment stays fast and free while the backend scales independently.