Deploy your Astro Site to GitHub Pages
You can use GitHub Pages to host an Astro website directly from a repository on GitHub.com.
How to deploy
Section titled How to deployYou 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.
-
Set the
site
and, if needed,base
options inastro.config.mjs
.astro.config.mjs import { defineConfig } from 'astro/config' export default defineConfig({ site: 'https://astronaut.github.io', base: '/my-repo', })
site
should behttps://<YOUR_USERNAME>.github.io
orhttps://my-custom-domain.com
base
should be your repository’s name starting with a forward slash, for example/my-repo
. This is so that Astro understands your website’s root is/my-repo
, rather than the default/
.
-
Create a new file in your project at
.github/workflows/deploy.yml
and paste in the YAML below.deploy.yml name: Github Pages Astro CI 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@v2 - name: Install, build, and upload your site uses: withastro/action@v0 # with: # path: . # The root location of your Astro project inside the repository. (optional) # node-version: 16 # The specific version of Node that should be used to build your site. Defaults to 16. (optional) # package-manager: yarn # 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
-
On GitHub, go to your repository’s Settings tab and find the Pages section of the settings.
-
Choose GitHub Actions as the Source of your site and press Save.
-
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.