GitHub Actions for deploying to GitHub Pages
Using the following workflow, you can deploy your static site to GitHub Pages with Static Site Generators (Hugo, MkDocs, Gatsby, GitBook, etc.)
- uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
This GitHub Pages Action, Hugo Action, and mdBook Action were featured at the GitHub Blog. Thanks all!
For more details, go to https://github.com/peaceiris/actions-gh-pages 👇
peaceiris / actions-gh-pages
GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Static-Site-Generators-friendly.
GitHub Pages Action
Note
See also the GitHub official GitHub Pages Action first.
This is a GitHub Action to deploy your static files to GitHub Pages This deploy action can be combined simply and freely with Static Site Generators. (Hugo, MkDocs, Gatsby, mdBook, Next, Nuxt, and so on.)
The next example step will deploy ./public
directory to the remote gh-pages
branch.
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
For newbies of GitHub Actions:
Note that the GITHUB_TOKEN
is NOT a personal access token.
A GitHub Actions runner automatically creates a GITHUB_TOKEN
secret to authenticate in your workflow.
So, you can start to deploy immediately without any configuration.
Supported Tokens
Three tokens are supported.
Token | Private repo | Public |
---|
Getting Started
An example YAML file (.github/workflows/gh-pages.yml
) with Hugo action.
peaceiris / actions-hugo
GitHub Actions for Hugo ⚡️ Setup Hugo quickly and build your site fast. Hugo extended, Hugo Modules, Linux (Ubuntu), macOS, and Windows are supported.
GitHub Actions for Hugo
This Hugo Setup Action can install Hugo to a virtual machine of GitHub Actions Hugo extended version, Hugo Modules, Linux (Ubuntu), macOS, and Windows are supported.
From v2
, this Hugo Setup Action has migrated to a JavaScript (TypeScript) action
We no longer build or pull a Hugo docker image.
Thanks to this change, we can complete this action in less than a few seconds.
(A docker base action was taking about 1 min or more execution time to build and pull a docker image.)
OS (runs-on) | ubuntu-latest, ubuntu-20.04, ubuntu-22.04 | macos-latest | windows-2019 |
---|---|---|---|
Support | ✅️ | ✅️ | ✅️ |
Hugo type | Hugo Extended | Hugo Modules | Latest Hugo |
---|---|---|---|
Support | ✅️ | ✅️ | ✅️ |
Table of Contents
name: github pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v4
with:
submodules: true # Fetch Hugo themes
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
- name: Setup Hugo
uses: peaceiris/actions-hugo@v3
with:
hugo-version: '0.85.0'
- name: Build
run: hugo --minify
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
if: ${{ github.ref == 'refs/heads/main' }}
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
Options
Many options are available! Go to the repository (peaceiris/actions-gh-pages) and check the latest README.
Other Examples
⭐ Static Site Generators with Node.js
next.js, nuxt.js, gatsby, hexo, gitbook, vuepress, react-static, gridsome, etc. (JavaScript projects)
Premise: Dependencies are managed by package.json
and package-lock.json
name: github pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '14'
- name: Cache dependencies
uses: actions/cache@v4
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
⭐️ Static Site Generators with Python
pelican, MkDocs, sphinx, and so on.
Premise: Dependencies are managed by requirements.txt
name: github pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: '3.8'
architecture: 'x64'
- name: Cache dependencies
uses: actions/cache@v4
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
- name: Install dependencies
run: |
python3 -m pip install --upgrade pip
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
⭐️ mdBook (Rust)
An example GitHub Actions workflow to deploy rust-lang/mdBook site to GitHub Pages.
name: github pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v4
- name: Setup mdBook
uses: peaceiris/actions-mdbook@v2
with:
mdbook-version: '0.4.10'
# mdbook-version: 'latest'
- 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
⭐️ Flutter Web
An exapmle workflow for Flutter web project.
name: github pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v4
- name: Setup Flutter
run: |
git clone https://github.com/flutter/flutter.git --depth 1 -b beta _flutter
echo "::add-path::${GITHUB_WORKSPACE}/_flutter/bin"
- 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
⭐️ Elm
An exapmle workflow for Elm.
name: github pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
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
⭐️ github/personal-website
- github/personal-website - Code that'll help you kickstart a personal website that showcases your work as a software developer.
# .github/workflows/github-pages.yml
name: GitHub Pages
on:
push:
branches:
- master
schedule:
- cron: '24 */24 * * *' # Once a day
jobs:
deploy:
runs-on: ubuntu-22.04
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v4
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./
allow_empty_commit: true
enable_jekyll: true
cname: github.peaceiris.com
⭐️ Swift Publish
An example workflow for JohnSundell/Publish.
name: GitHub Pages
on:
push:
branches:
- main
pull_request:
jobs:
deploy:
runs-on: ubuntu-22.04
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- uses: actions/checkout@v4
- name: Setup JohnSundell/Publish
run: |
cd ${HOME}
git clone --depth=1 https://github.com/JohnSundell/Publish.git
cd ./Publish
swift build -c release
echo "::add-path::${HOME}/Publish/.build/release"
- 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
Check more options and examples on GitHub. peaceiris/actions-gh-pages
That's all! Enjoy GitHub Actions and Static Site Generators!
Top comments (2)
Here is the new workflow with peaceiris/actions-gh-pages v3.
This action has been migrated to a TypeScript Action. Your job will complete faster than v2.
such an underrated article. thanks for showing me how to do this!