How to Deploy an Astro Site to GitHub Pages for Free

GitHub Pages is free hosting for personal sites and projects. A host is a computer that never turns off. Once set up, your site puts itself online again each time you push a change. A push is when you send your changes up to GitHub. You need a free GitHub account. Your project must be in a GitHub repository. A repository is a project folder stored on GitHub.

Step 1: Tell Astro your site’s address

Open astro.config.mjs. This is your site’s settings file. Set site and base. Swap your-username and my-repo for your own names:

import { defineConfig } from 'astro/config';

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

With base set, your own links must start with it too. For example, /my-repo/about. Is your repository named your-username.github.io? Then you can leave base out.

Step 2: Add a workflow file

A workflow file is a list of steps for GitHub to run. Make .github/workflows/deploy.yml. Keep the dot at the start of the folder name:

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 your repository using git
        uses: actions/checkout@v7
      - name: Install, build, and upload your site
        uses: withastro/action@v6

  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@v5

Make sure your lockfile is committed too. One example is package-lock.json. The action uses it to work out which package manager you use.

Step 3: Turn on GitHub Pages

Go to your repository on GitHub. Open Settings, then Pages. Under Source, choose GitHub Actions.

Step 4: Push your changes

Commit your files. Then push them to the main branch. Open the Actions tab on GitHub to watch your site build. When it finishes, your site is live at https://your-username.github.io/my-repo.

Did the build fail? Click the failed step to read the error. Then check our common errors guide.

Frequently asked questions

Can I use GitHub Pages for my business site?

GitHub says Pages is not for running an online business, store or commercial service. Pick a different host for those sites.

Can I use a custom domain?

Yes. Set up DNS with your domain provider. Add a public/CNAME file that holds your domain. Set site to your domain. Then remove the base option.