Skip to content

deployment-github-pages.md

Latest commit

 

History

History
221 lines (155 loc) · 4.99 KB

deployment-github-pages.md

File metadata and controls

221 lines (155 loc) · 4.99 KB

Deploying to GitHub Pages

GitHub Pages is one of the easiest and completely FREE ways to deploy your landing page. It comes with SSL, CDN, and custom domain support—all at zero cost.

Prerequisites

  • A GitHub account (free)
  • Your landing page repository on GitHub
  • Built project files in the dist folder

Cost

100% FREE - No credit card required, no limits for static sites.

Method 1: Automatic Deployment with GitHub Actions (Recommended)

This method automatically builds and deploys your site whenever you push changes to your repository.

Step 1: Create GitHub Actions Workflow

  1. In your repository, create the directory structure: .github/workflows/
  2. Create a file named deploy.yml in that folder with this content:
name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main  # Change to your default branch if different

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Build project
        run: npm run build

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

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Step 2: Enable GitHub Pages

  1. Go to your repository on GitHub
  2. Click Settings → Pages
  3. Under "Source", select GitHub Actions
  4. Click Save

Step 3: Push and Deploy

  1. Commit the workflow file:

    git add .github/workflows/deploy.yml
git commit -m "Add GitHub Pages deployment workflow"
git push

  2. GitHub Actions will automatically build and deploy your site

  3. Check the Actions tab to see the deployment progress

  4. Your site will be live at: https://yourusername.github.io/repository-name/

Method 2: Manual Deployment

If you prefer to build locally and deploy manually:

Step 1: Build Your Project

npm run build

Step 2: Install gh-pages Package

npm install --save-dev gh-pages

Step 3: Add Deploy Script

Add this to your package.json scripts section:

"scripts": {
  "deploy": "gh-pages -d dist"
}

Step 4: Deploy

npm run deploy

Step 5: Configure GitHub Pages

  1. Go to Settings → Pages
  2. Under "Source", select Deploy from a branch
  3. Select the gh-pages branch
  4. Click Save

Your site will be live at: https://yourusername.github.io/repository-name/

Adding a Custom Domain

Step 1: Add CNAME File

Create a file named CNAME in your src folder (not dist) with your domain:

yourdomain.com

Or with a subdomain:

landing.yourdomain.com

Step 2: Configure DNS at Your Domain Registrar

Add these DNS records:

For apex domain (yourdomain.com):

Type: A
Name: @
Value: 185.199.108.153

Type: A
Name: @
Value: 185.199.109.153

Type: A
Name: @
Value: 185.199.110.153

Type: A
Name: @
Value: 185.199.111.153

For subdomain (landing.yourdomain.com):

Type: CNAME
Name: landing
Value: yourusername.github.io

Step 3: Configure Custom Domain in GitHub

  1. Go to Settings → Pages
  2. Enter your custom domain in the "Custom domain" field
  3. Click Save
  4. Wait for DNS check to complete (can take up to 48 hours)
  5. Enable "Enforce HTTPS" once DNS is verified

Troubleshooting

404 Errors on Page Refresh

If you're using client-side routing, create a 404.html file in your src folder that redirects to index.html.

Build Fails in GitHub Actions

  • Check that your package.json has all required dependencies
  • Verify Node.js version in workflow matches your development environment
  • Review build logs in the Actions tab

Custom Domain Not Working

  • Wait 24-48 hours for DNS propagation
  • Use dig yourdomain.com to check DNS records
  • Make sure CNAME file is in the root of your deployed branch

Performance Benefits

  • Global CDN: Your site is served from GitHub's CDN
  • Free SSL: Automatic HTTPS certificates
  • Fast Deployment: Changes go live in 1-2 minutes
  • Version Control: Easy rollbacks via Git

Limitations

  • Static sites only (perfect for this landing page!)
  • 1GB repository size limit
  • 100GB bandwidth per month (very generous)
  • 10 builds per hour limit

Next Steps

  • Monitor your deployments in the Actions tab
  • Set up custom domain for professional branding
  • Use GitHub's analytics to track page views (Settings → Traffic)

Cost Summary: $0/month forever Deployment Time: 1-2 minutes per deployment Difficulty: Easy 🟢