Skip to content

Deploy your Astro Site to GitHub Pages

This content is not available in your language yet.

You can use GitHub Pages to host an Astro website directly from a repository on GitHub.com.

You can deploy an Astro site to GitHub Pages by using GitHub Actions to automatically build and deploy your site. To do this, your source code must be hosted on GitHub.

Astro maintains the official withastro/action to deploy your project with very little configuration. Follow the instructions below to deploy your Astro site to GitHub pages, and see the package README if you need more information.

Configure Astro for GitHub Pages

Section titled Configure Astro for GitHub Pages

Set the site and base options in astro.config.mjs.

astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
site: 'https://astronaut.github.io',
base: '/my-repo',
})

The value for site must be one of the following:

  • The following URL based on your username: https://<username>.github.io
  • The random URL autogenerated for a GitHub Organization’s private page: https://<random-string>.pages.github.io/

A value for base may be required so that Astro will treat your repository name (e.g. /my-repo) as the root of your website.

The value for base should be your repository’s name starting with a forward slash, for example /my-blog. This is so that Astro understands your website’s root is /my-repo, rather than the default /.

Using GitHub pages with a custom domain

Section titled Using GitHub pages with a custom domain

To configure Astro for using GitHub pages with a custom domain, set your domain as the value for site. Do not set a value for base:

astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
site: 'https://example.com',
})
  1. Create a new file in your project at .github/workflows/deploy.yml and paste in the YAML below.

    deploy.yml
    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@v3
    - name: Install, build, and upload your site
    uses: withastro/action@v1
    # with:
    # path: . # The root location of your Astro project inside the repository. (optional)
    # node-version: 18 # The specific version of Node that should be used to build your site. Defaults to 18. (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@v1
  2. On GitHub, go to your repository’s Settings tab and find the Pages section of the settings.

  3. Choose GitHub Actions as the Source of your site.

  4. Commit the new workflow file and push it to GitHub.

Your site should now be published! When you push changes to your Astro project’s repository, the GitHub Action will automatically deploy them for you.

Więcej poradników wdrażania

Filtruj po typie wdrażania