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.
Configure Astro for GitHub Pages
Section titled Configure Astro for GitHub PagesDeplpoying to a github.io
URL
Section titled Deplpoying to a github.io URLSet the site
and base
options in astro.config.mjs
.
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.
Don’t set a base
parameter if:
- Your page is served from the root folder.
- Your repository is located at
https://github.com/<USERNAME>/<USERNAME>.github.io
.
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 /
.
When this value is configured, all of your internal page links must be prefixed with your base
value:
See more about configuring a base
value
Using GitHub pages with a custom domain
Section titled Using GitHub pages with a custom domainYou can set up a custom domain by adding the following ./public/CNAME
file to your project:
This will deploy your site at your custom domain instead of user.github.io
. Don’t forget to also configure DNS for your domain provider.
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
:
Configure a GitHub Action
Section titled Configure a GitHub Action-
Create a new file in your project at
.github/workflows/deploy.yml
and paste in the YAML below.The astro action takes a few optional inputs. These can be provided by uncommenting the
with:
line and the input you want to use.The official Astro action scans for a lockfile to detect your preferred package manager (
npm
,yarn
,pnpm
, orbun
). You should commit your package manager’s automatically generatedpackage-lock.json
,yarn.lock
,pnpm-lock.yaml
, orbun.lockb
file to your repository. -
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.
-
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.