Repository files navigation

🪂 A GitHub Action to deploy the Jekyll site conveniently for GitHub Pages.

JEKYLL DEPLOY ACTION

As we known, GitHub Pages runs insafe mode and aset of allow-listed plugins. To use the gem in GitHub Pages, you need to build locally or use CI (e.g.travis,github workflow) and deploy to yourgh-pages branch.

Therefore, if you want to make Jekyll site run as if it were local, such as letthe custom plugins work properly, this action can be very useful for you,beacause it's really convenient to build and deploy the Jekyll site to GithubPages.

At First, you should add a github workflow file (e.g..github/workflows/build-jekyll.yml) in your repository'smaster branch as below:

name:Build and Deploy to Github Pageson:push:branches:      -master# Here source code branch is `master`, it could be other branchjobs:build_and_deploy:runs-on:ubuntu-lateststeps:      -uses:actions/checkout@v4# Use GitHub Actions' cache to cache dependencies on servers      -uses:actions/cache@v4with:path:|            .asdf/**            vendor/bundlekey:${{ runner.os }}-cache-${{ hashFiles('**/cache.key') }}restore-keys:|            ${{ runner.os }}-cache-# Use GitHub Deploy Action to build and deploy to Github# For the latest version: `jeffreytse/jekyll-deploy-action@master`      -uses:jeffreytse/jekyll-deploy-action@v0.7.0with:provider:'github'# Default is githubtoken:${{ secrets.GITHUB_TOKEN }}# It's your Personal Access Token(PAT)ssh_private_key:''# It's your SSH private key (SSH approach)repository:''# Default is current repositorybranch:'gh-pages'# Default is gh-pages for github providerjekyll_src:'./'# Default is root directoryjekyll_cfg:'_config.yml'# Default is _config.ymljekyll_baseurl:''# Default is according to _config.ymlruby_ver:''# Default is 3.2.0 versionbundler_ver:''# Default is compatible bundler version (~>2.5.0)cname:''# Default is to not use a cnameactor:''# Default is the GITHUB_ACTORpre_build_commands:''# Installing additional dependencies (Arch Linux)

Now this action supports the following providers:

• github: To publish the site to GitHub.
• test: To check if build passes on pull requests without publishing the site.
• ssh: To publish the site into any server which supports SSH protocol.
• ...

To schedule a workflow, you can use the POSIX cron syntax in your workflow file.The shortest interval you can run scheduled workflows is once every 5 minutes.For example, this workflow is triggered every hour.

on:schedule:    -cron:'0 * * * *'

At the start of each workflow run, GitHub automatically creates a uniqueGITHUB_TOKEN secret to use in your workflow. You can use theGITHUB_TOKENto authenticate in a workflow run. You can use theGITHUB_TOKEN by using thestandard syntax for referencing secrets:${{ secrets.GITHUB_TOKEN }}. Formore information, you can seehere.

If you need a token that requires permissions that aren't available in theGITHUB_TOKEN, you can create a Personal Access Token (PAT), and set it asa secret in your repository for this action to push to thegh-pages branch:

• Create aPersonal Access Token with custom permissions and copy the value.
• Go to your repository’s Settings and then switch to the Secrets tab.
• Create a token namedGH_TOKEN (important) using the value copied.

In the end, go to your repository’s Settings and scroll down to the GitHub Pagessection, choose thegh-pages branch as your GitHub Pages source.

Additionally, if you don't have thegh-pages branch, you can create it as below:

git checkout --orphan gh-pagesgit rm -rf.git commit --allow-empty -m"initial commit"git push origin gh-pages

💡 Tip: Thegh-pages branch is only for the site static files and themaster branch is for source code.

If you usejekyll-last-modified-at plugin, you can configure the checkout action to fetch all commit history so that plugin could use the last Git commit date to determine a page's last modified date.

-uses:actions/checkout@v3with:# The checkout action doesn't provide a way to get all commit history for a single branch# So we use the magic number 2147483647 here which means infinite depth for git fetch# See https://github.com/actions/checkout/issues/520, https://stackoverflow.com/a/6802238fetch-depth:2147483647

If your site building needs some specific environments, here are some recipesfor you:

# NodeJSpre_build_commands:pacman -S --noconfirm nodejs npm# Pythonpre_build_commands:pacman -S --noconfirm python# Gem RMagickpre_build_commands:pacman -S --noconfirm imagemagick# Jekyll-Picture-Tagpre_build_commands:pacman -S --noconfirm libvips lcms2 openjpeg2 libpng libwebp libheif imagemagick openslide libjxl poppler-glib

If you prefer to deploy your site in SSH approach for better stability, you canalso creates a uniqueSSH_PRIVATE_KEY secret to use in your workflow:

ssh_private_key:${{ secrets.SSH_PRIVATE_KEY }}

Note: SSH approach has higher priority than HTTP approach when you provideboth at the same time.

• Jekyll - A blog-aware static site generator in Ruby.
• actions/checkout - Action for checking out a repo.
• actions/cache - Cache dependencies and build outputs in GitHub Actions.

Issues and Pull Requests are greatly appreciated. If you've never contributed to an open source project before I'm more than happy to walk you through how to create a pull request.

You can start byopening an issue describing the problem that you're looking to resolve and we'll go from there.

This software is licensed under theMIT license © JeffreyTse.