Skip to main content
← Back to workflows

How to Deploy GitHub Pages with GitHub Action?

peaceiris/actions-gh-pages -
GitHub Action
actions-github-pages v4.0.0
4,461
Contributors
Contributor - peaceiris
CICUBE ANALYTICS INSIGHTS
Engineering Velocity: 25% Team Time Lost to CI Issues
View Platform →
3.5h
Time Saved/Dev/Week
40%
Faster Releases
Click for next insight
Usage
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

OpenCommit logo

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.

TokenPrivate repoPublic repoProtocolSetup
github_token✅️✅️HTTPSUnnecessary
deploy_key✅️✅️SSHNecessary
personal_token✅️✅️HTTPSNecessary

Supported Platforms

All Actions runners: Linux (Ubuntu), macOS, and Windows are supported.

runs-ongithub_tokendeploy_keypersonal_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!