How to Deploy Your Project to GitHub Pages: A Complete Guide

GitHub Pages is a powerful and free hosting service that lets you publish websites directly from your GitHub repository. Whether you’ve built your project using Bolt.new, Lovable.dev, or other AI development tools, GitHub Pages offers a seamless way to get your site live on the internet. In this guide, we’ll walk through the process of deploying your project to GitHub Pages, all from your browser.

What is GitHub Pages?

GitHub Pages is a free hosting service provided by GitHub that allows you to publish websites directly from your GitHub repositories. It works with HTML, CSS, and JavaScript, making it perfect for static websites. While it’s free for public repositories, you’ll need a GitHub Pro plan for private repositories.

Prerequisites

Before we begin, you’ll need:

A GitHub account
A project repository on GitHub
Basic familiarity with Git and GitHub

Step-by-Step Deployment Guide

1. Initial Setup

First, we need to configure your project for GitHub Pages deployment. This is a one-time setup – after this, every commit to your main branch will automatically deploy to GitHub Pages.

Update package.json

Open your package.json file and add the homepage field right after the name field:

{
  "name": "your-project-name",
  "homepage": "https://yourusername.github.io/repository-name",
  ...
}

2. Set Up GitHub Actions Workflow

Create a new directory structure in your root directory:
.github/workflows/

Inside the workflows directory, create a new file called deploy.yml with the following configuration:

name: GitHub Pages

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: write

    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install Dependencies
        run: npm install

      - name: Build Project
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Let’s break down what this workflow does:

Workflow Triggers: The workflow runs automatically when code is pushed to the main branch or when a pull request is created.
Environment Setup: It uses an Ubuntu virtual machine and sets up Node.js version 20.
Build Process:
- Checks out your code
- Installs dependencies
- Builds the project
Deployment: Publishes the built files to GitHub Pages using the peaceiris/actions-gh-pages action.

3. Configure Vite (If Using Vite)

If your project uses Vite, you’ll need to modify the vite.config.js file to ensure proper asset loading on GitHub Pages:

export default defineConfig({
  base: './',  // or '/your-repository-name/'
  // ... other config options
})

4. Deploy Your Site

Commit and push your changes to GitHub
Go to your repository’s Settings > Pages
Under “Build and deployment”, set the deployment branch to gh-pages
Wait for the GitHub Actions workflow to complete
Your site will be live at https://yourusername.github.io/repository-name

Using a Custom Domain (Optional)

If you want to use a custom domain:

Update your GitHub Actions workflow to include a CNAME:

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  if: github.ref == 'refs/heads/main'
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./dist
    cname: your-domain.com

Set up DNS:
- Go to your DNS provider
- Create a CNAME record pointing to yourusername.github.io
Configure GitHub Pages:
- Go to repository Settings > Pages
- Enter your custom domain
- Wait for DNS verification
- Enable “Enforce HTTPS” once available

Troubleshooting Tips

If your deployment fails, check the GitHub Actions logs for specific error messages
Ensure your package.json homepage field matches your GitHub Pages URL
Verify that your vite.config.js base property is set correctly
For custom domains, allow time for DNS propagation (usually a few hours)

Additional Resources

Conclusion

GitHub Pages provides a robust, free hosting solution for your static websites. With GitHub Actions, you can automate your deployment process and focus on developing your project. Whether you’re using it for documentation, personal projects, or client work, GitHub Pages offers a professional-grade hosting platform that integrates seamlessly with your development workflow.

Remember to check the official documentation for the most up-to-date information and advanced configuration options. Happy deploying!

AI-Driven Coder