Skip to main content

Deploying

Astro’s build output goes into dist/, deployable to any static hosting provider.

GitHub Pages

The starter example ships a ready-made workflow at .github/workflows/deploy.yml; copy it into any site. It provisions Node and pnpm from the project’s mise.toml, builds with SITE_URL and BASE_PATH derived from the repository name, and publishes dist/ through the official Pages actions. (The two actions/cache steps for the pnpm store and Astro’s build cache are trimmed here.)

# .github/workflows/deploy.yml
name: deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

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

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
      - uses: jdx/mise-action@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
        env:
          SITE_URL: https://${{ github.repository_owner }}.github.io
          BASE_PATH: /${{ github.event.repository.name }}
      - uses: actions/configure-pages@v6
      - uses: actions/upload-pages-artifact@v5
        with:
          path: dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 5
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    steps:
      - id: deploy
        uses: actions/deploy-pages@v5

In the repository settings, set Pages → Source to “GitHub Actions” once. A project site is served at https://<owner>.github.io/<repo>/, so BASE_PATH is /<repo>; for a user or organisation site (a repository named <owner>.github.io) set it to /. The theme’s link checker verifies that every internal link carries the base prefix, so a link that would 404 on the live site fails the build instead.

Cloudflare Pages

Connect your repository in the Cloudflare Pages dashboard, then configure:

Netlify

Connect the repository and set:

You can also add a netlify.toml to your repository:

[build]
  command = "pnpm build"
  publish = "dist"

Base path configuration

If your site isn’t served from the domain root, astro.config.ts’s base option prefixes all internal links and asset paths automatically. This applies to every deployment target, not just GitHub Pages.

import { defineConfig } from "astro/config";

export default defineConfig({
  site: "https://example.com",
  base: "/docs",
});

When base is set, use Astro’s built-in URL handling rather than hard-coding paths; import.meta.env.BASE_URL gives the base path at runtime.