How to Deploy an Astro Site to GitHub Pages for Free

GitHub Pages is free hosting for personal sites and projects. Once it’s set up, your site republishes itself each time you push a change. You’ll need a free GitHub account, and your project needs to be in a GitHub repository.

Step 1: Tell Astro your site’s address

Open astro.config.mjs and set site and base. Replace your-username and my-repo with your own names:

import { defineConfig } from 'astro/config';

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

With base set, your internal links must start with it too, for example /my-repo/about. You can leave base out if your repository is named your-username.github.io.

Step 2: Add a workflow file

Create .github/workflows/deploy.yml, including 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, such as package-lock.json, is committed as well. The action uses it to work out which package manager you use.

Step 3: Turn on GitHub Pages

In your repository on GitHub, go to Settings, then Pages. Under Source, choose GitHub Actions.

Step 4: Push your changes

Commit your files and 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.

If the build fails, 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 isn't for running an online business, store or commercial service. Choose 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 containing your domain, set site to your domain, and remove the base option.