Improve this page

CircleCI

Building, testing, and deploying your Jekyll-generated website can quickly be done with CircleCI, a continuous integration & delivery tool. CircleCI supports GitHub and Bitbucket, and you can get started for free using an open-source or private repository.

1. Follow Your Project on CircleCI

To start building your project on CircleCI, all you need to do is ‘follow’ your project from CircleCI’s website:

  1. Visit the ‘Add Projects’ page
  2. From the GitHub or Bitbucket tab on the left, choose a user or organization.
  3. Find your project in the list and click ‘Build project’ on the right.
  4. The first build will start on its own. You can start telling CircleCI how to build your project by creating a .circleci/config.yml file in the root of your repository.

2. Dependencies

The easiest way to manage dependencies for a Jekyll project (with or without CircleCI) is via a Gemfile. You’d want to have Jekyll, any Jekyll plugins, HTML Proofer, and any other gems that you are using in the Gemfile. Don’t forget to version Gemfile.lock as well. Here’s an example Gemfile:

source 'https://rubygems.org'

ruby '2.7.4'

gem "jekyll"
gem "html-proofer"

    - step:
       run: bundle install

3. Testing

The most basic test that can be run is seeing if jekyll build actually works. This is a blocker, a dependency if you will, for other tests you might run on the generate site. So we’ll run Jekyll, via Bundler, in the dependencies phase.

    - step:
        run: bundle exec jekyll build

HTML Proofer

With your site built, it’s useful to run tests to check for valid HTML, broken links, etc. There’s a few tools out there but HTML Proofer is popular amongst Jekyll users. We’ll run it in the test phase with a few preferred flags. Check out the html-proofer README for all available flags, or run htmlproofer --help locally.

    - step:
        run: bundle exec htmlproofer ./_site --check-html --disable-external

Complete Example .circleci/config.yml File

The example .circleci/config.yml below demonstrates how to deploy your Jekyll project to AWS. In order for this to work you would first have to set the S3_BUCKET_NAME environment variable.

workflows:
  test-deploy:
    jobs:
      - build
      - deploy:
          requires:
            - build
          filters:
            branches:
              only: master
version: 2.1
jobs:
  build:
    docker:
      - image: cimg/ruby:2.7.4
    environment:
      BUNDLE_PATH: ~/repo/vendor/bundle
    steps:
      - checkout
      - restore_cache:
          keys:
            - rubygems-v1-{{ checksum "Gemfile.lock" }}
            - rubygems-v1-fallback
      - run:
          name: Bundle Install
          command: bundle check || bundle install
      - save_cache:
          key: rubygems-v1-{{ checksum "Gemfile.lock" }}
          paths:
            - vendor/bundle
      - run:
          name: Jekyll build
          command: bundle exec jekyll build
      - run:
          name: HTMLProofer tests
          command: |
            bundle exec htmlproofer ./_site \
              --allow-hash-href \
              --check-favicon  \
              --check-html \
              --disable-external
      - persist_to_workspace:
          root: ./
          paths:
            - _site
  deploy:
    docker:
      - image: cimg/python:3.9.1
    environment:
      S3_BUCKET_NAME: <<YOUR BUCKET NAME HERE>>
    steps:
      - attach_workspace:
          at: ./
      - run:
          name: Install AWS CLI
          command: pip install awscli --upgrade --user
      - run:
          name: Upload to s3
          command: ~/.local/bin/aws s3 sync ./_site s3://$S3_BUCKET_NAME/ --delete --acl public-read

Questions?

This entire guide is open-source. Go ahead and edit it if you have a fix or ask for help if you run into trouble and need some help. CircleCI also has an online community for help.