name: GitHub Pages
on:
push:
branches:
- main # Set a branch name to trigger deployment
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
permissions:
contents: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v3
with:
submodules: true # Fetch Hugo themes (true OR recursive)
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: '0.110.0'
- name: Build
run: hugo --minify
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
# If you're changing the branch from main,
# also change the `main` in `refs/heads/main`
# below accordingly.
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
GitHub Pages Action for GitHub Pages
What is GitHub Pages Action?
This tool is part of GitHub Actions and automates the deployment of our website directly to GitHub Pages every time we push updates to our repository. It's super handy for sites that get updated frequently.
Here’s a quick rundown:
- Automated Updates: It automatically refreshes our GitHub Pages site whenever we make changes to the specified branch, eliminating the need for manual uploads.
- Customizable Workflows: We can set it up to trigger under the conditions we choose, making sure it fits perfectly with our project's workflow.
- Seamless Integration: It works smoothly alongside other GitHub Actions, which helps in setting up a robust CI/CD pipeline.
- Support for Static Site Generators: If we’re using tools like Jekyll, Hugo, or Gatsby, GitHub Pages Action can handle their build processes and deploy them without any extra steps.
Why it’s beneficial?
Using GitHub Pages Action means we're always sure that the latest version of our site is live as soon as we push changes. It removes the manual steps and lets us focus more on development. Plus, it ensures that our deployments are consistent and error-free.
Supported Tokens
Three tokens are supported.
Token | Private repo | Public repo | Protocol | Setup |
---|---|---|---|---|
github_token | ✅️ | ✅️ | HTTPS | Unnecessary |
deploy_key | ✅️ | ✅️ | SSH | Necessary |
personal_token | ✅️ | ✅️ | HTTPS | Necessary |
Supported Platforms
All Actions runners: Linux (Ubuntu), macOS, and Windows are supported.
runs-on | github_token | deploy_key | personal_token |
---|---|---|---|
ubuntu-22.04 | ✅️ | ✅️ | ✅️ |
ubuntu-20.04 | ✅️ | ✅️ | ✅️ |
ubuntu-latest | ✅️ | ✅️ | ✅️ |
macos-latest | ✅️ | ✅️ | ✅️ |
windows-latest | ✅️ | (2) | ✅️ |
How to use GitHub Pages Action for Static Site Generators with Node.js?
This example details how to deploy static sites like Hexo, VuePress, React-Static, Gridsome, or a Create React App project using GitHub Pages Action. Before setting up your workflow, make sure you know where your build output directory is, for instance, create-react-app
outputs to ./build
.
Here’s a sample workflow setup for deploying a Node.js based static site:
name: GitHub Pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
permissions:
contents: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: '14'
- name: Cache dependencies
uses: actions/cache@v3
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- run: npm ci
- run: npm run build
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
How to use GitHub Pages Action with Gatsby?
Deploying a Gatsby site to GitHub Pages can be efficiently managed with this GitHub Action. Ensure your project follows the standard Gatsby workflow.
Here’s how you can set up the GitHub Action for a Gatsby project:
name: GitHub Pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
permissions:
contents: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: '14'
- name: Cache dependencies
uses: actions/cache@v3
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- run: npm ci
- run: npm run format
- run: npm run test
- run: npm run build
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
How to use GitHub Pages Action with React and Next?
For projects using Next.js, a React framework, the deployment process involves building static HTML and JavaScript files. Here’s a setup for deploying a Next.js project:
name: GitHub Pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
permissions:
contents: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: '14'
- name: Get yarn cache
id: yarn-cache
run: echo "YARN_CACHE_DIR=$(yarn cache dir)" >> "${GITHUB_OUTPUT}"
- name: Cache dependencies
uses: actions/cache@v3
with:
path: ${{ steps.yarn-cache.outputs.YARN_CACHE_DIR }}
key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
${{ runner.os }}-yarn-
- run: yarn install --frozen-lockfile
- run: yarn build
- run: yarn export
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./out
This setup ensures that your React/Next.js project is built and deployed seamlessly to GitHub Pages, managing dependencies and cache effectively to optimize the build and deployment process.
Sure, let's continue with the configurations for Vue/Nuxt, Docusaurus, Python-based static site generators, and others:
How to use GitHub Pages Action with Vue and Nuxt?
For deploying a Nuxt.js (Vue.js framework) project, here’s how you can set up the GitHub Action. This example assumes that you are generating a static site with Nuxt.js.
name: GitHub Pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
permissions:
contents: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: '14'
- name: Cache dependencies
uses: actions/cache@v3
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
- run: npm ci
- run: npm test
- run: npm run generate
- name: deploy
uses: peaceiris/actions-gh-pages@v4
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist
How to use GitHub Pages Action with Docusaurus?
Here’s how to set up a workflow for deploying a Docusaurus site. This example assumes you are using Yarn as your package manager.
# .github/workflows/deploy.yml
name: GitHub Pages
on:
push:
branches:
- main
paths:
- '.github/workflows/deploy.yml'
- 'website/**'
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
permissions:
contents: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
defaults:
run:
working-directory: website
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: '14'
- name: Get yarn cache
id: yarn-cache
run: echo "YARN_CACHE_DIR=$(yarn cache dir)" >> "${GITHUB_OUTPUT}"
- name: Cache dependencies
uses: actions/cache@v3
with:
path: ${{ steps.yarn-cache.outputs.YARN_CACHE_DIR }}
key: ${{ runner.os }}-website-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
${{ runner.os }}-website-
- run: yarn install --frozen-lockfile
- run: yarn build
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./website/build
How to use GitHub Pages Action for Static Site Generators with Python?
Here's how to set up a GitHub Pages deployment for Python-based static site generators like Pelican, MkDocs, or Sphinx.
name: GitHub Pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
permissions:
contents: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v3
- name: Setup Python
uses: actions/setup-python@v3
with:
python-version: '3.8'
- name: Upgrade pip
run: |
python3 -m pip install --upgrade pip
- name: Get pip cache dir
id: pip-cache
run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT
- name: Cache dependencies
uses: actions/cache@v3
with:
path: ${{ steps.pip-cache.outputs.dir }}
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
- run: python3 -m pip install -r ./requirements.txt
- run: mkdocs build
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir:
./site
How to use GitHub Pages Action with mdBook (Rust)?
If you're using mdBook, a popular static site generator for Rust, here's how you can deploy your documentation to GitHub Pages.
name: GitHub Pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
permissions:
contents: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v3
- name: Setup mdBook
uses: peaceiris/actions-mdbook@v1
with:
mdbook-version: '0.4.8'
- run: mdbook build
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./book
How to use GitHub Pages Action with Flutter Web?
For deploying Flutter web projects, you can set up a workflow like this:
name: GitHub Pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
permissions:
contents: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v3
- name: Setup Flutter
run: |
git clone https://github.com/flutter/flutter.git --depth 1 -b beta _flutter
echo "${GITHUB_WORKSPACE}/_flutter/bin" >> ${GITHUB_PATH}
- name: Install
run: |
flutter config --enable-web
flutter pub get
- name: Build
run: flutter build web
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./build/web
How to use GitHub Pages Action with Elm?
For Elm projects, you can deploy your site to GitHub Pages using this workflow:
name: GitHub Pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
permissions:
contents: write
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: '14'
- name: Setup Elm
run: npm install elm --global
- name: Make
run: elm make --optimize src/Main.elm
- name: Move files
run: |
mkdir ./public
mv ./index.html ./public/
# If you have non-minimal setup with some assets and separate html/js files,
# provide --output=<output-file> option for `elm make` and remove this step
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
How to use GitHub Pages Action with Swift Publish?
Finally, for Swift Publish projects, you can deploy your site to GitHub Pages with the following workflow:
name: GitHub Pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: macos-latest
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v3
- uses: actions/cache@v3
with:
path: |
~/Publish_build
.build
key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}
restore-keys: |
${{ runner.os }}-spm-
- name: Setup JohnSundell/Publish
run: |
cd ${HOME}
export PUBLISH_VERSION="0.7.0"
git clone https://github.com/JohnSundell/Publish.git
cd ./Publish && git checkout ${PUBLISH_VERSION}
mv ~/Publish_build .build || true
swift build -c release
cp -r .build ~/Publish_build || true
echo "${HOME}/Publish/.build/release" >> ${GITHUB_PATH}
- run: publish-cli generate
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v4
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./Output
These configurations should help you deploy a variety of projects to GitHub Pages using GitHub Actions. Let me know if you need further assistance!