1. Enabling Travis and GitHub
To enable Travis builds for your GitHub repository:
- Go to your profile on travis-ci.org: https://travis-ci.org/profile/username
- Find the repository for which you’re interested in enabling builds.
- Flick the repository switch on so that it turns blue.
- Optionally configure the build by clicking on the gear icon. Further
configuration happens via your
.travis.ymlfile. More details below.
2. The Test Script
The simplest test script runs
jekyll build and ensures that Jekyll
doesn’t fail to build the site. It doesn’t check the resulting site, but it
does ensure things are built properly.
When testing Jekyll output, there is no better tool than html-proofer.
This tool checks your resulting site to ensure all links and images exist.
Utilize it either with the convenient
htmlproofer command-line executable,
or write a Ruby script which utilizes the gem.
Save the commands you want to run and succeed in a file:
The HTML Proofer Executable
#!/usr/bin/env bash set -e # halt script on error bundle exec jekyll build bundle exec htmlproofer ./_site
Some options can be specified via command-line switches. Check out the
html-proofer README for more information about these switches, or run
htmlproofer --help locally.
For example to avoid testing external sites, use this command:
bundle exec htmlproofer ./_site --disable-external
The HTML Proofer Library
You can also invoke
html-proofer in Ruby scripts (e.g. in a Rakefile):
#!/usr/bin/env ruby require 'html-proofer' HTMLProofer.check_directory("./_site").run
Options are given as a second argument to
.new, and are encoded in a
symbol-keyed Ruby Hash. For more information about the configuration options,
html-proofer’s README file.
3. Configuring Your Travis Builds
This file is used to configure your Travis builds. Because Jekyll is built
with Ruby and requires RubyGems to install, we use the Ruby language build
environment. Below is a sample
.travis.yml file, followed by
an explanation of each line.
Note: You will need a Gemfile as well, Travis will automatically install the dependencies based on the referenced gems. Here is an example
Gemfile with two referenced gems, “jekyll” and “html-proofer”:
source "https://rubygems.org" gem "jekyll" gem "html-proofer"
.travis.yml file should look like this:
language: ruby rvm: - 2.4.1 before_script: - chmod +x ./script/cibuild # or do this locally and commit # Assume bundler is being used, therefore # the `install` step will run `bundle install` by default. script: ./script/cibuild # branch whitelist, only for GitHub Pages branches: only: - gh-pages # test the gh-pages branch - /pages-(.*)/ # test every branch which starts with "pages-" env: global: - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer addons: apt: packages: - libcurl4-openssl-dev sudo: false # route your build to the container-based infrastructure for a faster build cache: bundler # caching bundler gem packages will speed up build # Optional: disable email notifications about the outcome of your builds notifications: email: false
Ok, now for an explanation of each line:
This line tells Travis to use a Ruby build container. It gives your script access to Bundler, RubyGems, and a Ruby runtime.
rvm: - 2.4.1
RVM is a popular Ruby Version Manager (like rbenv, chruby, etc). This directive tells Travis the Ruby version to use when running your test script. Use a version which is pre-installed on the Travis build docker image to speed up the build.
before_script: - chmod +x ./script/cibuild
The build script file needs to have the executable attribute set or Travis will fail with a permission denied error. You can also run this locally and commit the permissions directly, thus rendering this step irrelevant.
Travis allows you to run any arbitrary shell script to test your site. One
convention is to put all scripts for your project in the
directory, and to call your test script
cibuild. This line is completely
customizable. If your script won’t change much, you can write your test
incantation here directly:
install: gem install jekyll html-proofer script: jekyll build && htmlproofer ./_site
script directive can be absolutely any valid shell command.
# branch whitelist, only for GitHub Pages branches: only: - gh-pages # test the gh-pages branch - /pages-(.*)/ # test every branch which starts with "pages-"
You want to ensure the Travis builds for your site are being run only on
the branch or branches which contain your site. One means of ensuring this
isolation is including a branch whitelist in your Travis configuration
file. By specifying the
gh-pages branch, you will ensure the associated
test script (discussed above) is only executed on site branches. If you use
a pull request flow for proposing changes, you may wish to enforce a
convention for your builds such that all branches containing edits are
prefixed, exemplified above with the
/pages-(.*)/ regular expression.
branches directive is completely optional. Travis will build from every
push to any branch of your repo if leave it out.
env: global: - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer
html-proofer? You’ll want this environment variable. Nokogiri, used
to parse HTML files in your compiled site, comes bundled with libraries
which it must compile each time it is installed. Luckily, you can
dramatically decrease the install time of Nokogiri by setting the
Be sure to exclude
vendor from your
Travis bundles all gems in the
vendor directory on its build
servers, which Jekyll will mistakenly read and explode on.
By default you should supply the
sudo: false command to Travis. This command
explicitly tells Travis to run your build on Travis’s container-based
infrastructure. Running on the container-based infrastructure can often times
speed up your build. If you have any trouble with your build, or if your build
sudo access, modify the line to
To speed up the build, you should cache the gem packages created by
Travis has a pre-defined cache strategy for this tool which should have
all the default configs to do exactly that.
Optionally, if you are not interested in the build email notifications you can disable them with this configuration. Travis supports a wide array of notification services, you may find another one more useful (e.g. slack).
notifications: email: false
Travis error: “You are trying to install in deployment mode after changing your Gemfile. Run bundle install elsewhere and add the updated Gemfile.lock to version control.”
Workaround: Either run
bundle install locally and commit your changes to
Gemfile.lock, or remove the
Gemfile.lock file from your repository and add
an entry in the
.gitignore file to avoid it from being checked in again.