Deploying Astro to GitHub Pages Guide: A Step-by-Step Tutorial

Astro has quickly become one of my favorite frameworks for content-heavy websites because of its ‘zero-JS by default’ approach. However, the real magic happens when you get your site live. If you’re looking for a free, reliable way to host your project, this deploying Astro to GitHub Pages guide will walk you through the process from start to finish.

In my experience, GitHub Pages is an excellent choice for portfolios, blogs, and documentation. While I’ve often compared Astro vs Next.js for static sites, Astro’s simplicity makes it a natural fit for the JAMstack workflow. Let’s get your site deployed.

Prerequisites

Before we dive into the deployment, ensure you have the following ready:

• An existing Astro project (if you don’t have one, run npm create astro@latest).
• A GitHub account and a repository where your code is pushed.
• Node.js installed on your local machine.
• Basic familiarity with Git commands.

Step 1: Configure Your Astro Site

GitHub Pages usually hosts sites at username.github.io/repo-name/. Because your site is in a subfolder, you need to tell Astro about it, otherwise, your CSS and images will break.

Open your astro.config.mjs file and add the site and base properties:

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://your-username.github.io',
  base: '/your-repo-name',
});

Pro Tip: If you are deploying to a custom domain or a User page (e.g., username.github.io), you can omit the base property. I highly recommend using a custom domain if this is a professional portfolio to avoid the subfolder headache.

Step 2: Set Up GitHub Actions

Manually building your site and pushing a /dist folder is tedious and error-prone. Instead, we’ll use GitHub Actions to automate the build process. This is the gold standard for best free hosting for static sites because it ensures your live site always matches your main branch.

1. In your GitHub repository, go to Settings > Pages.
2. Under Build and deployment > Source, change the dropdown to GitHub Actions.

Now, you need to create a workflow file. In your project root, create a folder path: .github/workflows/deploy.yml. Paste the following configuration:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install, build, and upload
        uses: withastro/action@v2

As shown in the image below, this workflow triggers every time you push to the main branch, automatically handling the installation and deployment phases.

Step 3: Pushing and Verifying

Now, let’s push the changes to GitHub:

git add .
git commit -m "Add GitHub Pages deployment workflow"
git push origin main

Navigate to the Actions tab in your GitHub repository. You should see a workflow run in progress. Once it turns green, your site is live! You can find the URL under Settings > Pages.

Pro Tips for Astro Deployment

• Handling Assets: When using a base path, always reference your images and links starting with the base path. For example: .
• Optimizing Performance: I’ve found that using Astro’s Image component significantly reduces LCP (Largest Contentful Paint) on GitHub Pages.
• Migration: If you’re moving from an older stack, check out my guide on how to migrate Gatsby to Astro to save time on content restructuring.

Troubleshooting Common Issues

404 Errors on Sub-pages

If your homepage works but internal pages return a 404 upon refresh, it’s likely because GitHub Pages doesn’t natively support Single Page Application (SPA) routing. However, since Astro generates static HTML files, this is rarely an issue unless you’ve misconfigured your base path.

CSS Not Loading

Check your browser console. If you see 404s for CSS files, your base configuration in astro.config.mjs is likely missing or incorrect. Ensure it matches your repository name exactly.

What’s Next?

Now that your site is live, you might want to explore adding a headless CMS like Contentful or Sanity to manage your posts without touching code. Alternatively, if you find GitHub Pages too limiting for your growing project, you might consider Vercel or Netlify for more advanced edge functions.