Overview

GitHub Actions allows automatic deployment of static sites to GitHub Pages whenever code is pushed to the repository. This eliminates manual file uploads and creates a seamless CI/CD pipeline.

Prerequisites

• Public GitHub repository (GitHub Pages is free only for public repos)
• Node.js project with build script that outputs to a dist folder
• GitHub Pages enabled in repository settings with source set to "GitHub Actions"

Setup Steps

1. Create Directory Structure

mkdir -p .github/workflows

GitHub Actions requires workflows to be in .github/workflows/ directory.

2. Create Workflow File

Create .github/workflows/deploy.yml with the deployment configuration.

3. Enable GitHub Pages

• Go to repository Settings → Pages
• Set Source to "GitHub Actions" (not "Deploy from branch")

4. Commit and Push

Once the workflow file is committed and pushed, GitHub automatically runs the workflow on every push to the main branch.

Workflow Configuration

name: Deploy to 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:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '21'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build project
        run: npm run build

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'

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

Configuration Elements Explained

Triggers

• on: push: branches: [main] - Runs workflow when code is pushed to main branch
• workflow_dispatch - Allows manual triggering from GitHub web interface

Permissions

• contents: read - Read repository contents
• pages: write - Write to GitHub Pages
• id-token: write - Required for GitHub Pages deployment

Concurrency

• group: "pages" - Ensures only one deployment runs at a time
• cancel-in-progress: false - Don't cancel running deployments

Jobs

Build Job

1. Checkout - Downloads repository code to runner
2. Setup Node.js - Installs Node.js v21 with npm caching
3. Install dependencies - Runs npm ci (faster than npm install)
4. Build project - Runs npm run build script
5. Setup Pages - Configures GitHub Pages environment
6. Upload artifact - Uploads dist folder contents for deployment

Deploy Job

• needs: build - Only runs after build job succeeds
• environment: github-pages - Uses GitHub Pages deployment environment
• Deploys the uploaded artifact to GitHub Pages

Key Benefits

• Automatic deployment - Triggered by pushing to your main branch
• Version control - All deployments are tied to git commits
• Build verification - Catches build errors before deployment
• Rollback capability - Easy to revert to previous deployments

Site URL

After successful deployment, site is available at: https://[username].github.io/[repository-name]/

Monitoring

• View workflow runs in repository's "Actions" tab
• See deployment status and logs
• Monitor build times and success rates