github.com/peaceiris/actions-gh-pages @v4.1.0 sqlite

GitHub Pages Action

[!NOTE]

See also the GitHub official GitHub Pages Action first.

• GitHub Pages now uses Actions by default | The GitHub Blog
• GitHub Pages: Custom GitHub Actions Workflows (beta) | GitHub Changelog

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 repo	Protocol	Setup
github_token	✅️	✅️	HTTPS	Unnecessary
deploy_key	✅️	✅️	SSH	Necessary
personal_token	✅️	✅️	HTTPS	Necessary

Notes: Actually, the GITHUB_TOKEN works for deploying to GitHub Pages but it has still some limitations. For the first deployment, we need to select the gh-pages branch or another branch on the repository settings tab. See First Deployment with GITHUB_TOKEN

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)	✅️

1. WIP, See Issue #87

GitHub Enterprise Server Support

✅️ GitHub Enterprise Server is supported above 2.22.6.

Note that the GITHUB_TOKEN that is created by the runner might not inherently have push/publish privileges on GHES. You might need to create/request a technical user with write permissions to your target repository.

Table of Contents

• Getting started
• Options
• ⭐️ Set Runner's Access Token github_token
• ⭐️ Set SSH Private Key deploy_key
• ⭐️ Set Personal Access Token personal_token
• ⭐️ Set Another GitHub Pages Branch publish_branch
• ⭐️ Source Directory publish_dir
• ⭐️ Deploy to Subdirectory destination_dir
• ⭐️ Filter publishing assets exclude_assets
• ⭐️ Add CNAME file cname
• ⭐️ Enable Built-in Jekyll enable_jekyll
• ⭐️ Allow empty commits allow_empty_commit
• ⭐️ Keeping existing files keep_files
• ⭐️ Deploy to external repository external_repository
• ⭐️ Force orphan force_orphan
• ⭐️ Set Git username and email
• ⭐️ Set custom commit message
• ⭐️ Create Git tag
• Tips and FAQ
• ⭐️ Create SSH Deploy Key
• ⭐️ First Deployment with GITHUB_TOKEN
• ⭐️ Use the latest and specific release
• ⭐️ Schedule and Manual Deployment
• ⭐️ Release Strategy
• Examples
• ⭐️ Static Site Generators with Node.js
• ⭐️ Gatsby
• ⭐️ React and Next
• ⭐️ Vue and Nuxt
• ⭐️ Docusaurus
• ⭐️ Static Site Generators with Python
• ⭐️ mdBook (Rust)
• ⭐️ Flutter Web
• ⭐️ Elm
• ⭐️ Swift Publish
• License
• Maintainer

Getting started

Add your workflow file .github/workflows/gh-pages.yml and push it to your remote default branch.

Here is an example workflow for Hugo.

• peaceiris/actions-hugo: GitHub Actions for Hugo

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@v4
        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

Actions log overview	GitHub Pages log

Back to TOC ☝️

Options

⭐️ Set Runner's Access Token github_token

This option is for GITHUB_TOKEN, not a personal access token.

A GitHub Actions runner automatically creates a GITHUB_TOKEN secret to use in your workflow. You can use the GITHUB_TOKEN to authenticate in a workflow run.

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public

For more details about GITHUB_TOKEN: Automatic token authentication - GitHub Docs

⭐️ Set SSH Private Key deploy_key

Read Create SSH Deploy Key, create your SSH deploy key, and set the deploy_key option like the following.

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

⭐️ Set Personal Access Token personal_token

Generate a personal access token (repo) and add it to Secrets as PERSONAL_TOKEN, it works as well as ACTIONS_DEPLOY_KEY.

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    personal_token: ${{ secrets.PERSONAL_TOKEN }}
    publish_dir: ./public

⭐️ Set Another GitHub Pages Branch publish_branch

Set a branch name to use as GitHub Pages branch. The default is gh-pages.

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_branch: your-branch  # default: gh-pages

⭐️ Source Directory publish_dir

A source directory to deploy to GitHub Pages. The default is public. Only the contents of this dir are pushed to GitHub Pages branch, gh-pages by default.

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./out  # default: public

⭐️ Deploy to Subdirectory destination_dir

This feature is on beta. Any feedback is welcome at Issue #324

A destination subdirectory on a publishing branch. The default is empty.

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    destination_dir: subdir

⭐️ Filter publishing assets exclude_assets

This feature is on beta. Any feedback is welcome at Issue #163

Set files or directories to exclude from publishing assets. The default is .github. Values should be split with a comma.

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    exclude_assets: '.github,exclude-file1,exclude-file2'

Set exclude_assets to empty for including the .github directory to deployment assets.

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}   # Recommended for this usage
    # personal_token: ${{ secrets.PERSONAL_TOKEN }} # An alternative
    # github_token: ${{ secrets.GITHUB_TOKEN }}     # This does not work for this usage
    exclude_assets: ''

The exclude_assets option supports glob patterns.

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    exclude_assets: '.github,exclude-file.txt,exclude-dir/**.txt'

⭐️ Add CNAME file cname

To add the CNAME file, we can set the cname option. Alternatively, put your CNAME file into your publish_dir. (e.g. public/CNAME)

For more details about the CNAME file, read the official documentation: Managing a custom domain for your GitHub Pages site - GitHub Docs

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public
    cname: github.com

⭐️ Enable Built-in Jekyll enable_jekyll

If you want GitHub Pages to process your site with the static site generator Jekyll, set enable_jekyll to true.

By default, this action signals to GitHub Pages that the site shall not be processed with Jekyll. This is done by adding an empty .nojekyll file on your publishing branch. When that file already exists, this action does nothing.

Bypassing Jekyll makes the deployment faster and is necessary if you are deploying files or directories that start with underscores, since Jekyll considers these to be special resources and does not copy them to the final site. You only need to set enable_jekyll to true when you want to deploy a Jekyll-powered website and let GitHub Pages do the Jekyll processing.

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public
    enable_jekyll: true

For more details about .nojekyll: Bypassing Jekyll on GitHub Pages - The GitHub Blog

⭐️ Allow empty commits allow_empty_commit

By default, a commit will not be generated when no file changes. If you want to allow an empty commit, set the optional parameter allow_empty_commit to true.

For example:

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public
    allow_empty_commit: true

⭐️ Keeping existing files keep_files

By default, existing files in the publish branch (or only in destination_dir if given) will be removed. If you want the action to add new files but leave existing ones untouched, set the optional parameter keep_files to true.

Note that users who are using a Static Site Generator do not need this option in most cases. Please reconsider your project structure and building scripts, or use a built-in