When building a Jekyll site with GitHub Pages, the standard flow is restricted for security reasons and to make it simpler to get a site setup. For more control over the build and still host the site with GitHub Pages you can use GitHub Actions.
3.9.0
, you can use any version of Jekyll you want. For example 4.0.0
, or point directly to the repository.*.rb
files placed in the _plugins
directory of your site.The first and foremost requirement is a Jekyll project hosted at GitHub. Choose an existing Jekyll project or follow the Quickstart and push the repository to GitHub if it is not hosted there already.
We’re only going to cover builds from the master
branch in this page. Therefore, ensure that you are working on the master
branch. If necessary, you may create it based on your default branch. When the Action builds your site, the contents of the destination directory will be automatically pushed to the gh-pages
branch with a commit, ready to be used for serving.
The Action we’re using here will create (or reset an existing)gh-pages
branch on every successful deploy. So, if you have an existinggh-pages
branch that is used to deploy your production build, ensure to make a backup of the contents into a different branch so that you can rollback easily if necessary.
The Jekyll site we’ll be using for the rest of this page initially consists of just a _config.yml
, an index.md
page and a Gemfile
. The contents are respectively:
# _config.yml title: "Jekyll Actions Demo"
--- --- Welcome to My Home Page {% assign date = '2020-04-13T10:20:00Z' %} - Original date - {{ date }} - With timeago filter - {{ date | timeago }}
# Gemfile source 'https://rubygems.org' gem 'jekyll', '~> 4.0' group :jekyll_plugins do gem 'jekyll-timeago', '~> 0.13.1' end
The demo site uses Jekyll 4 and a third-party plugin, both of which are currently not whitelisted for use on GitHub pages. The plugin will allow us to describe how far back a date was from today. e.g. If we give a date as2016-03-23T10:20:00Z
and the current date is2020-04-13T10:20:00Z
, then the output would be4 years and 3 weeks ago
.
The action we’re using takes care of installing the Ruby gems and dependencies. While that keeps the setup simple for the user, one may encounter issues if they also check-in Gemfile.lock
if it was generated with an old version of Bundler.
GitHub Actions are registered for a repository by using a YAML file inside the directory path .github/workflows
(note the dot at the start). Here we shall employ Jekyll Actions from the Marketplace for its simplicity.
Create a workflow file, say github-pages.yml
, using either the GitHub interface or by pushing a YAML file to the workflow directory path manually. The base contents are:
name: Build and deploy Jekyll site to GitHub Pages on: push: branches: - master jobs: github-pages: runs-on: ubuntu-16.04 steps: - uses: actions/checkout@v2 - uses: helaili/[email protected] env: JEKYLL_PAT: ${{ secrets.JEKYLL_PAT }}
The above workflow can be explained as the following:
master
branch only — this prevents the Action from overwriting the gh-pages
branch on any feature branch pushes.github-pages
.helaili/[email protected]
. This handles the build and deploy.JEKYLL_PAT
is a Personal Access Token and is detailed in the next section.Instead of using the on.push condition, you could trigger your build on a schedule by using the on.schedule parameter. For example, here we build daily at midnight by specifying cron syntax, which can be tested at the crontab guru site.
on: schedule: - cron: '0 0 * * *'
Note that this string must be quoted to prevent the asterisks from being evaluated incorrectly.
The action needs permissions to push to your gh-pages
branch. So you need to create a GitHub authentication token on your GitHub profile, then set it as an environment variable in your build using Secrets:
public_repos
(or the entire repo
scope for private repository) — necessary for the action to commit to the gh-pages
branch.JEKYLL_PAT
(important). Give it a value using the value copied above.On pushing any local changes onto master
, the action will be triggered and the build will start.
To watch the progress and see any build errors, check on the build status using one of the following approaches:
jekyll
workflow tab.If all goes well, all steps will be green and the built assets will now exist on the gh-pages
branch.
On a successful build, GitHub Pages will publish the site stored on the repository gh-pages
branches. Note that you do not need to setup a gh-pages
branch or enable GitHub Pages, as the action will take care of this for you. (For private repositories, you’ll have to upgrade to a paid plan).
To see the live site:
timeago
filter works as expected.README.md
, to make it easy for people to find.When you need to make further changes to the site, commit to master
and push. The workflow will build and deploy your site again.
Be sure not to edit the gh-pages
branch directly, as any changes will be lost on the next successful deploy from the Action.
jekyll-actions
action. That project can be used as a template for making a new site.
© 2020 Jekyll Core Team and contributors
Licensed under the MIT license.
https://jekyllrb.com/docs/continuous-integration/github-actions/