Deploy Astro to GitHub Pages

This action for Astro builds your static Astro project for GitHub Pages.

For more information, please see our complete deployment guide—Deploy your Astro Site to GitHub Pages.

Usage

Note: Want to get started even faster? Create a repository from our official GitHub Pages template!

Inputs

• path - Optional: the root location of your Astro project inside the repository.
• node-version - Optional: the specific version of Node that should be used to build your site. Defaults to 24.
• package-manager - Optional: the Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. Accepted values: npm, yarn, pnpm, bun, and deno. A version tag is also accepted, for example npm@11.6.2, pnpm@10, bun@latest, or deno@v2.x. If not provided, version will default to latest.
• build-cmd - Optional: the command to run to build your site. Defaults to deno task build for sites using Deno and to <package-manager> run build for all other package managers.
• cache - Optional: enable Astro build cache to speed up subsequent builds. Caches optimized images and other build assets. Defaults to true.
• cache-dir - Optional: path to the Astro cache directory (relative to path). Defaults to node_modules/.astro. Only used when cache is true.
• out-dir - Optional: path to the Astro output directory, as created by build (relative to path). Defaults to dist. This directory is artifacted by this action.

Example workflow:

Build and Deploy to GitHub Pages

Create a file at .github/workflows/deploy.yml with the following content.

name: Deploy to GitHub Pages

on:
  # Trigger the workflow every time you push to the `main` branch
  # Using a different branch name? Replace `main` with your branch’s name
  push:
    branches: [main]
  # Allows you to run this workflow manually from the Actions tab on GitHub.
  workflow_dispatch:

# Allow this job to clone the repo and create a page deployment
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v6
      - name: Install, build, and upload your site output
        uses: withastro/action@v6
        # with:
            # path: . # The root location of your Astro project inside the repository. (optional)
            # node-version: 24 # The specific version of Node that should be used to build your site. Defaults to 24. (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)
            # build-cmd: pnpm run build # The command to run to build your site. Runs the package build script/task by default. (optional)
            # out-dir: dist # The output directory created by the build command. Defaults to dist. (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