Jekyll - Deploy - CI/CD

   
   
 jekyll  
 ssg  
Article Series

Jekyll in General

Jekyll Plain

Jekyll Bootstrap OC

Jekyll Bulma MD

Conclusions

Repository

Where to Discuss?

Local Group

Table of Content

Preface

Goal: Overview of CI/CD for Jekyll, for intermediate user.

Introduction

This require CI/CD knowledge.

There are many ways to deploy Jekyll, rather than just using github pages.

Choice: Deploying Method

How many ways to deploy your static site? I found at least ten ways to deploy SSG site.

Illustration: Deploy Options

Target Reader

This article is not meant to be read, for beginner who does not know, how to build a simple jekyll site. If you do not know, what Jekyll is all about, please go back to repository overview.

What to Do on Each CI/CD

One step closer to be a YAML engineer.

Just writing configuration, mostly in YAML. Create trigger if necessary. Then upload to repository.

The CI/CD would do the jobs for you.

No Github Pages

If you use github repository, add .nojekyll to disable autmatic github pages generation.

4: Github Actions

Instead of github pages, we can utilize github actions

Article

I get this configuration originally from mas Didik. The article is in local language.

He did it really great. And I rewrite on my own article.

Configuration Artefact

  • .github/workflows/deploy.yml.

You can have any name, workflow directory.

YAML Configuration: Official Guidance

Jekyll has official documentation for Github Actions

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/jekyll-action@2.0.1
        env:
          JEKYLL_PAT: ${{ secrets.JEKYLL_PAT }}

YAML Configuration: Alternate Guidance

name: Jekyll Deploy

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout to master
      uses: actions/checkout@master
    - name: Set up Ruby 2.6
      uses: actions/setup-ruby@v1
      with:
        ruby-version: 2.6.x
    - name: Install Gems and Configure Dependencies
      run: |
        gem install bundler
        bundle install --jobs 4 --retry 3        
    - name: Deploy Static Files to gh-pages Branch
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: |
        bundle exec rake site:publish

Github Workflows: Jekyll Run Checkout

Rakefile

What is it this rake is all about? Ruby use a file named Rakefile. I copy-paste Didik’s Rakefile, and adjust a little. You can get Didik’s Rakefile from:

And I trace the source come from

After a few adjustment, my Rakefile looks like below code:

require "rubygems"
require "tmpdir"

require "bundler/setup"
require "jekyll"

# Change your GitHub reponame 
# eg. "kippt/jekyll-incorporated"
# or "id-ruby/id-ruby"
GITHUB_REPONAME = "epsi-rns/workflows-jekyll"
GITHUB_TOKEN    = ENV["GITHUB_TOKEN"]


namespace :site do
  desc "Generate blog files"
  task :generate do
    Jekyll::Site.new(Jekyll.configuration({
      "source"      => ".",
      "destination" => "_site"
    })).process
  end


  desc "Generate and publish blog to gh-pages"
  task :publish => [:generate] do
    current_directory = Dir.pwd

    Dir.mktmpdir do |tmp|
      cp_r "_site/.", tmp
      Dir.chdir tmp
      system "git init"
      system "git config user.name someone"
      system "git config user.email someone@somewhere"
      system "git add ."
      message = "Site updated at #{Time.now.utc}"
      system "git commit -m #{message.inspect}"
      system "git remote add origin #{git_origin}"
      system "git push origin master:refs/heads/gh-pages --force"
      Dir.chdir current_directory
    end
  end

  def git_origin
    if GITHUB_TOKEN
      "https://x-access-token:#{GITHUB_TOKEN}@github.com/#{GITHUB_REPONAME}.git"
    else
      "git@github.com:#{GITHUB_REPONAME}.git"
    end
  end
end

Wow… I have so much to learn from this Rakefile. You have done great job, mr. Didik!.

5: Gitlab CI

Configuration Artefact

  • .gitlab-ci.yml.

YAML Configuration: Official Guidance

image: ruby:latest

variables:
  JEKYLL_ENV: production
  LC_ALL: C.UTF-8

before_script:
  - gem install bundler
  - bundle install

test:
  stage: test
  script:
  - bundle exec jekyll build -d test
  artifacts:
    paths:
    - test
  except:
  - master

pages:
  stage: deploy
  script:
  - bundle exec jekyll build -d public
  artifacts:
    paths:
    - public
  only:
  - master

I run Gitlab CI for my Jekyll Bootstrap Examples.

Gitlab CI: Jekyll Bootstrap Examples

6: Netlify

Article

I never try Jekyll on Netlify APP. I use netlify for my Hexo site. But I think Jekyll should also works.

Configuration Artefact

Not mandatory, but you can use one.

  • netlify.toml.

Official Guidance

7: Vercel (Zeit Now)

You must link your Vercel account with, either github, gitlab or bitbucket.

Article

I also write an article about Vercel App.

Configuration Artefact

Not required.

Vercel Configuration

Vercel App: Jekyll on Bitbucket

Live Site

My Jekyll on bitbucket repository run well with Vercel.

8: Travis

Travis do the jobs for you. Without the need to type git commands.

Article

Configuration Artefact

  • .travis.yml.

YAML Configuration:

language: ruby
rvm:
  - 2.6.3

before_script: bundle install
script: bundle exec jekyll build

deploy:
  local-dir: _site
  provider: pages
  skip-cleanup: true

  # Set in travis-ci.org dashboard, marked secure
  github-token: $GITHUB_TOKEN
  keep-history: true
  on:
    branch: master

Travis: Jekyll on Github

9: CircleCI

Articles

Configuration Artefact

  • .circleci/config.yml.

YAML Configuration

I use a low level approach. Accessing git directly.

version: 2

# https://jtway.co/deploying-jekyll-to-github-pages-with-circleci-2-0-3eb69324bc6e
# https://willschenk.com/articles/2018/automating_hugo_with_circleci/

workflows:
  version: 2
  build:
    jobs:
      - buildsite:
         filters:
            branches:
              only: master

jobs:
  buildsite:
    docker:
      # Choose Image that Support Git Worktree Command
      - image: circleci/ruby:2.4
    working_directory: ~/source
    environment:
      BUILD_DIR: ~/public
    steps:
      - checkout
      - add_ssh_keys:
          fingerprints:
            - "dc:18:73:7a:1a:a7:5f:92:31:67:cb:20:eb:0f:77:31"
      - run:
          name: Prepare Git Initialization
          command: |
            git config user.email "someone@somewhere"
            git config user.name "someone"
            git branch -a -l | cat
            if [ $(git branch -a -l | grep gh-pages | wc -l) -eq "0" ]; then
              echo "[Create gh-pages for the first time]"
              git checkout -b gh-pages
              git commit --allow-empty -m "Create gh-pages for the first time"
              git push --set-upstream origin gh-pages
              git checkout master
            fi            
      - run: bundle install
      - run: bundle exec jekyll build
      - deploy:
          name: Precheck Output 
          command: |
            git worktree add -B gh-pages $BUILD_DIR origin/gh-pages
            git worktree list
            cd $BUILD_DIR
            ls -lah
            find . -maxdepth 1 ! -name '.git' -exec rm -rf {} \;
            mv ~/source/_site/* .
            touch .nojekyll
            ls -lah            
      - deploy:
          name: Deploy Release to GitHub
          command: |
            cd $BUILD_DIR
            git add --all
            git status
            git commit --allow-empty -m "[skip ci] $(git log master -1 --pretty=%B)"
            git push --set-upstream origin gh-pages
            echo "[Deployed Successfully]"

CircleCI: Jekyll Steps Skeleton

10: Manual

This is a long journey, that deserve its own articles.

Articles

You can read it here.

Worktree

I utilize git worktree command.

This below is an example for Pelican, but this should also works with Jekyll.

git worktree: Two Panes tmux, prepare HEAD for each branches

Conclusion

There are many ways to deploy Jekyll. Once it build, you can put a CNAME, so that the result displayed in your very own domain.

Confused?

Although this CI/CD article is not for beginner. You should not get intimidated by the YAML configuration. This article meant to be an CI/CD overview for Jekyll, You can learn easily, by following the tutorial step by step, because there is guidance in detail over the CI/CD article series. You can thoroughly read, start from this article.

What’s Next?

We are done with jekyll plain, and also deployment. We still have jekyll with stylesheet to cover. Put on clothes to our plain jekyll, and make the blog looks fashionable.

Consider continue reading: to [ Jekyll - Bootstrap OC - Repository ], or [ Jekyll - Bulma MD - Repository ].

Thank you for reading.