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

If you’ve recently started building with Astro, you’ve likely noticed how incredibly fast the development experience is. But the real magic happens when you move from localhost:4321 to a live URL. In this deploying Astro to GitHub Pages guide, I’ll show you exactly how to set up an automated pipeline so that every time you push code to your repository, your site updates automatically.

I’ve experimented with various hosting providers, and while there are many best free hosting for static sites options out there, GitHub Pages remains a top choice for developers because it keeps your code and deployment in one place. Whether you are coming from a legacy setup or wondering Astro vs Nextjs for static sites, the deployment process for a static Astro site is remarkably straightforward.

Prerequisites

Before we dive into the deployment steps, make sure you have the following ready:

• An Astro project already initialized and committed to a GitHub repository.
• A GitHub account with administrative access to the repo.
• Basic familiarity with the terminal and Git commands.

Step 1: Configure Your Astro Site

GitHub Pages usually hosts sites at username.github.io/repo-name/. This means your site is in a subfolder, which can break your CSS and image links if not configured correctly. I’ve run into this issue many times—forgetting the site and base properties is the #1 reason for “404 Not Found” assets after deployment.

Open your astro.config.mjs file and update it as follows:

import { defineConfig } from 'astro/config';

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

Replace yourusername with your actual GitHub username and your-repo-name with the name of your repository. If you are deploying to a custom domain, you can omit the base property.

Step 2: Setting Up GitHub Actions

Instead of building the site locally and pushing the dist folder (which is a nightmare for version control), we’ll use GitHub Actions. This creates a CI/CD pipeline that handles the build process on GitHub’s servers.

1. In your GitHub repository, click on the Settings tab. 2. Navigate to Pages in the left sidebar. 3. Under Build and deployment > Source, change the dropdown from “Deploy from a branch” to “GitHub Actions”.

As shown in the image below, this is the critical switch that tells GitHub to look for a workflow file rather than a static branch like gh-pages.

# Create this file at .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

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

Pro Tips for Astro Deployments

In my experience, a few small tweaks can make your site feel much more professional:

• Use a Custom Domain: GitHub Pages supports custom domains. Once configured, you can remove the base property from your config for cleaner URLs.
• Optimize Images: Use Astro’s built-in <Image> component. Since GitHub Pages is a static host, pre-optimizing images during the build process is essential for performance.
• Migration: If you’re moving from an older framework, you might find how to migrate Gatsby to Astro helpful for cleaning up your content structure before deployment.

Troubleshooting Common Issues

If your site isn’t appearing or looks like plain HTML without CSS, check these three things:

What’s Next?

Now that your site is live, you can focus on adding content and optimizing your SEO. If you find that your site is growing and you need server-side rendering (SSR) or a database, you might want to explore platforms like Vercel or Netlify. However, for 90% of blogs and portfolios, GitHub Pages is more than enough.

Ready to level up your site? Check out my other guides on automation and development to streamline your workflow further.