GitHub Pages now uses customizable GitHub Action workflows to build and deploy your code so that developers can control their authoring framework and deployment. GitHub Pages is a powerful option for storing static content for the following reasons:
- It’s free.
- It makes collaboration easy. Anyone can open a pull request to update the site.
- Your repository syncs with any changes you made to your site.
- While GitHub Pages comes with a default domain name like,
https://YOUR_USER_NAME.github.io/, it supports custom domains. - It uses customizable GitHub Action workflows for builds and deployments.
The team at GitHub made a few starter workflows available to you, so you don’t have to write them from scratch, and you can use them as examples to support deployments in other frameworks. Currently there are starter workflows for Next.js, Nuxt.js, Gatsby, Hugo, Jekyll, and HTML.
Let’s learn how to host static sites built with Astro or any workflow of your choice on GitHub Pages!
Please note that your repository must be public to publish your site on GitHub Pages.
After you write your code (using a framework or static generator of your choice) and store it in a repository, go to the settings tab for that repository.
Click Pages on the left sidebar
Under build and deployment, choose GitHub Actions
Create a folder at the root of your project called .github/workflows
Inside of your .github/workflows folder, create a customized workflow to deploy your specified framework to GitHub Pages (see examples in the section below):
Example workflow for Astro
name: Deploy Astro to GitHub Pages
on:
# Trigger the workflow every time you push to the `main` branch
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: Check out your repository using git
uses: actions/checkout@v2
- name: Use Node.js 16
uses: actions/setup-node@v2
with:
node-version: '16'
cache: 'npm'
# Not using npm? Change `npm ci` to `yarn install` or `pnpm i`
- name: Install dependencies
run: npm ci
# Not using npm? Change `npm run build` to `yarn build` or `pnpm run build`
- name: Build Astro
run: npm run build --if-present
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: ./dist
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1
Example workflow for React
name: Deploy to React GitHub Pages
on:
# Trigger the workflow every time you push to the `main` branch
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: Check out your repository using git
uses: actions/checkout@v2
- name: Use Node.js 16
uses: actions/setup-node@v2
with:
node-version: '16'
cache: 'npm'
# Not using npm? Change `npm ci` to `yarn install` or `pnpm i`
- name: Install dependencies
run: npm ci
# Not using npm? Change `npm run build` to `yarn build` or `pnpm run build`
- name: Build React
run: npm run build --if-present
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: ./build
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1
Example template for any static generator of your choice
name: Deploy to “your frameworks” GitHub Pages
on:
# Trigger the workflow every time you push to the `main` branch
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: Check out your repository using git
uses: actions/checkout@v2
- name: Use “REPLACE WITH THE RUNTIME OF YOUR CHOICE”
uses: “REPLACE WITH THE ACTION THAT SETS UP THE RUN TIME OF YOUR CHOICE”
# Not using npm? Change `npm ci` to `yarn install` or `pnpm i`
- name: Install dependencies
run: “REPLACE WITH COMMANDS TO INSTALL DEPENDENCIES”
# Not using npm? Change `npm run build` to `yarn build` or `pnpm run build`
- name: Build “YOUR STATIC GENERATOR HERE”
run: “REPLACE WITH YOUR BUILD COMMAND”
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: “REPLACE WITH YOUR BUILD OUTPUT FOLDER”
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1
Within a few seconds, your Action will start running. It will generate a URL and deploy your static site to GitHub Pages if successful.
Head over to your URL named yourusername.github.io/your_repo_name to check out your live website!
Gotchas: handling asset paths
When I first published my site on GitHub Pages, I was confused and surprised that I couldn’t see any images or PDFs even though they were present when I locally hosted the site. This happened because GitHub Pages handles paths differently.
For example, if I have PDF living in this relative path: assets/pdfs/menu-food.pdf, then once hosted on GitHub Pages, update the new path to {“REPOSITORY NAME”}/assets/pdfs/menu-food.pdf
Example
Here's an example repository I built using this method
blackgirlbytes
/
blackgyalbites-astro
no touch restaurant menu template hosted on GitHub Pages
blackgyalbites
Template for No-touch Menus and Host Static Pages Built with Any Framework on GitHub Pages
Website built with Astro to display restaurant menus when users scan a QR code.
Powered By GitHub Pages
This is a demonstration to show developers that they can build and host static websites using any framework. See more example frameworks hosted on GitHub Pages:
Link to live site: https://blackgirlbytes.github.io/blackgyalbites-astro/
Design and Development
All designs and elements are open source, available for free for anyone to use.
Owned by Rizel Scarlett (@blackgirlbytes)
Designed by The Holistic Technologist
Illustrations by Cuoc Doi Prints
Feel free to fork, copy, tweak, and use for any purpose. This project is completely open source, and under MIT license.
Menu Design Template: Canva
Download Assets & Design Elements: Google Drive
Learn more
- Watch this talk delivered by Tommy Byrd on Using GitHub Pages with Actions to deploy Hugo sites in seconds
- The repository and ReadMe for Deploy Pages
- GitHub’s changelog announcement
- Official GitHub Blog Post
Watch this awesome YouTube short by Kedasha demonstrating how to use a customized workflow to deploy a static site generator to GitHub Pages!
I'd love your thoughts on the new customized workflows to deploy to GitHub Pages. Comment below! For more content like this, follow GitHub and me on DEV!
Top comments (1)
Deploying an Astro site to GitHub Pages can be a complex and frustrating process. Without the right steps and guidance, it can be difficult to determine which files to deploy, how to properly configure the site, and how to effectively troubleshoot any issues that arise. Additionally, if users are unfamiliar of Matemáticas with GitHub, the process may seem daunting and difficult to understand. As a result, many users may be unsure of how to properly deploy an Astro site to GitHub Page