Deploying Astro to GitHub Pages

So you’ve built a beautiful Astro site (maybe even using some of the components from this blog!). Now it’s time to share it with the world. GitHub Pages is a fantastic, free hosting solution, and with GitHub Actions, we can automate the entire deployment process.

The Mission Plan

Here is the workflow we are going to implement:

Loading diagram...

Step 1: Configuration

First, we need to tell Astro where your site will live. Open your astro.config.mjs file.

You need to configure two key properties:

1. site: Your full domain (e.g., https://username.github.io).
2. base: The subpath if you are deploying to a project repo (e.g., /my-repo).

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://your-username.github.io',
  base: '/your-repo-name', // Remove this if deploying to username.github.io directly
});

Step 2: The Launch Sequence (GitHub Actions)

We need to create a workflow file that tells GitHub how to build and deploy our site.

Create a new file at .github/workflows/deploy.yml and paste the following:

name: Deploy to GitHub Pages

on:
  # Trigger the workflow every time you push to the `main` branch
  push:
    branches: [ main ]
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets the GITHUB_TOKEN permissions to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
      
      - name: Install, build, and upload your site
        uses: withastro/action@v2
        # with:
          # path: . # The root location of your Astro project inside the repository. (optional)
          # node-version: 20 # The specific version of Node that should be used to build your site. Defaults to 20. (optional)
          # package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)

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

Step 3: Mission Control Settings

Before we launch, we need to enable GitHub Pages in your repository settings.

1. Go to your repository on GitHub.
2. Click on Settings > Pages.
3. Under Build and deployment, select GitHub Actions as the source.

Step 4: Blast Off! 🚀

Now, simply commit your changes and push to GitHub.

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

Head over to the Actions tab in your repository. You should see your “Deploy to GitHub Pages” workflow running. Once it turns green, your site is live!