Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jeffreytse/jekyll-deploy-action

🪂 A Github Action to deploy the Jekyll site conveniently for GitHub Pages.
https://github.com/jeffreytse/jekyll-deploy-action

List: jekyll-deploy-action

actions actionscript awesome ci configuration deploy deployment gh-pages gihub-actions github-page github-workflow jekyll jekyll-site recommend schedule site ssh workflow

Last synced: about 2 months ago
JSON representation

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

Host: GitHub
URL: https://github.com/jeffreytse/jekyll-deploy-action
Owner: jeffreytse
License: mit
Created: 2020-07-01T08:12:45.000Z (about 4 years ago)
Default Branch: master
Last Pushed: 2024-04-05T07:24:20.000Z (6 months ago)
Last Synced: 2024-05-11T09:43:57.238Z (4 months ago)
Topics: actions, actionscript, awesome, ci, configuration, deploy, deployment, gh-pages, gihub-actions, github-page, github-workflow, jekyll, jekyll-site, recommend, schedule, site, ssh, workflow
Language: Shell
Homepage:
Size: 91.8 KB
Stars: 322
Watchers: 2
Forks: 43
Open Issues: 8
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt

Awesome Lists containing this project

awesome-jekyll-plugins - **Jekyll Deploy Action** - deploy-action](https://github.com/jeffreytse/jekyll-deploy-action)) -- 🪂 A Github Action to deploy the Jekyll site conveniently for GitHub Pages. (Upload & Deploy)
awesome - jeffreytse/jekyll-deploy-action - 🪂 A Github Action to deploy the Jekyll site conveniently for GitHub Pages. (Shell)
jekyll-spaceship - jekyll-deploy-action
project-awesome - jeffreytse/jekyll-deploy-action - 🪂 A Github Action to deploy the Jekyll site conveniently for GitHub Pages. (Shell)

README

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

JEKYLL DEPLOY ACTION

`Jekyll` action for deployment.

_{Built with ❤︎ by

jeffreytse and

contributors}

## ✨ Story

As we known, GitHub Pages runs in `safe` mode and a [set of allow-listed plugins](https://pages.github.com/versions/). To use the gem in GitHub Pages, you need to build locally or use CI (e.g. [travis](https://travis-ci.org/), [github workflow](https://help.github.com/en/actions/configuring-and-managing-workflows/configuring-a-workflow)) and deploy to your `gh-pages` branch.

**Therefore, if you want to make Jekyll site run as if it were local, such as let
the 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 Github
Pages.**

## 📚 Usage

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

```yml
name: Build and Deploy to Github Pages

on:
push:
branches:
- master # Here source code branch is `master`, it could be other branch

jobs:
build_and_deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

# Use GitHub Actions' cache to cache dependencies on servers
- uses: actions/cache@v4
with:
path: |
.asdf/**
vendor/bundle
key: ${{ runner.os }}-cache-${{ hashFiles('**/cache.key') }}
restore-keys: |
${{ runner.os }}-cache-

# Use GitHub Deploy Action to build and deploy to Github
# For latest version: `jeffreytse/jekyll-deploy-action@master`
- uses: jeffreytse/[email protected]
with:
provider: 'github' # Default is github
token: ${{ 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 repository
branch: 'gh-pages' # Default is gh-pages for github provider
jekyll_src: './' # Default is root directory
jekyll_cfg: '_config.yml' # Default is _config.yml
jekyll_baseurl: '' # Default is according to _config.yml
ruby_ver: '' # Default is 3.2.0 version
bundler_ver: '' # Default is compatible bundler version (~>2.5.0)
cname: '' # Default is to not use a cname
actor: '' # Default is the GITHUB_ACTOR
pre_build_commands: '' # Installing additional dependencies (Arch Linux)
```

Now this action supports the following providers:

- [x] `github`: To publish the site to GitHub.
- [x] `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.

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

At the start of each workflow run, GitHub automatically creates a unique
`GITHUB_TOKEN` secret to use in your workflow. You can use the `GITHUB_TOKEN`
to authenticate in a workflow run. You can use the `GITHUB_TOKEN` by using the
standard syntax for referencing secrets: `${{ secrets.GITHUB_TOKEN }}`. For
more information, you can see [here](https://docs.github.com/en/actions/security-guides/automatic-token-authentication).

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

- Create a [Personal Access Token](https://github.com/settings/tokens) with custom permissions and copy the value.
- Go to your repository’s Settings and then switch to the Secrets tab.
- Create a token named `GH_TOKEN` (important) using the value copied.

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

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

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

**💡 Tip:** The `gh-pages` branch is only for the site static files and the `master` branch is for source code.

## ✨ FAQ

If you use [jekyll-last-modified-at](https://github.com/gjtorikian/jekyll-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.

```yaml
- uses: actions/checkout@v3
with:
# 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/6802238
fetch-depth: 2147483647
```

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

```yaml
# NodeJS
pre_build_commands: pacman -S --noconfirm nodejs npm

# Python
pre_build_commands: pacman -S --noconfirm python

# Gem RMagick
pre_build_commands: pacman -S --noconfirm imagemagick

# Jekyll-Picture-Tag
pre_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 can
also creates a unique `SSH_PRIVATE_KEY` secret to use in your workflow:

```yml
ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}
```

__Note:__ SSH approach has higher priority than HTTP approach when you provide
both at the same time.

## 🌱 Credits

- [Jekyll](https://github.com/jekyll/jekyll) - A blog-aware static site generator in Ruby.
- [actions/checkout](https://github.com/actions/checkout) - Action for checking out a repo.
- [actions/cache](https://github.com/actions/cache) - Cache dependencies and build outputs in GitHub Actions.

## ✍️ Contributing

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 by [opening an issue](https://github.com/jeffreytse/jekyll-deploy-action/issues/new) describing the problem that you're looking to resolve and we'll go from there.

## 🌈 License