DEV Community

peaceiris
peaceiris

Posted on • Updated on

Deploy to GitHub Pages with GitHub Actions for Static Site Generator

#github #githubpages #githubactions #hugo

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
Enter fullscreen mode Exit fullscreen mode

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 👇

GitHub logo peaceiris / actions-gh-pages

GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Static-Site-Generators-friendly.

GitHub Pages Action

GitHub Actions for deploying to GitHub Pages with Static Site Generators

license release GitHub release date Test Code Scanning CodeFactor

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
Enter fullscreen mode Exit fullscreen mode

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
…
View on GitHub

Getting Started

An example YAML file (.github/workflows/gh-pages.yml) with Hugo action.

GitHub logo 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

GitHub Actions for Hugo

Project status: active – The project has reached a stable, usable state and is being actively developed. license release GitHub release date Release Feed Test Code Scanning

CodeFactor codecov Maintainability

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

View on GitHub

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

⭐️ 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
Enter fullscreen mode Exit fullscreen mode

⭐️ 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
Enter fullscreen mode Exit fullscreen mode

⭐️ 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
Enter fullscreen mode Exit fullscreen mode

⭐️ 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
Enter fullscreen mode Exit fullscreen mode

⭐️ 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
Enter fullscreen mode Exit fullscreen mode

⭐️ 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
Enter fullscreen mode Exit fullscreen mode

Check more options and examples on GitHub. peaceiris/actions-gh-pages

That's all! Enjoy GitHub Actions and Static Site Generators!

Oldest comments (2)

Collapse
 
joellau profile image
Joel Lau •

such an underrated article. thanks for showing me how to do this!

Collapse
 
peaceiris profile image
peaceiris •

Here is the new workflow with peaceiris/actions-gh-pages v3.

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          publish_dir: ./public

This action has been migrated to a TypeScript Action. Your job will complete faster than v2.

Read next

manueltb profile image

Manuel's Article

Manuel -

hjgonzalez06 profile image

How to Choose the Proper License for your Project (and Why It Matters)

Hiram Gonzalez -

rachelfazio profile image

What is the best advice you have ever received?: CodeNewbie Podcast

Rachel Fazio -

harsimranjit_singh_0133dc profile image

Bias and Variance Tradeoff

Harsimranjit Singh -