dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rework CI doc to include multiple providers.

This commit is contained in:
Ricardo N Feliciano 2017-01-19 19:29:09 -05:00
parent 2a56e9ce0d
commit 3a3ceff150
No known key found for this signature in database
GPG Key ID: 71677F04C919CB01
5 changed files with 350 additions and 226 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

240
docs/_docs/continuous-integration.md
View File

@ -1,232 +1,20 @@
---
title: Continuous Integration
permalink: /docs/continuous-integration/
---
You can easily test your website build against one or more versions of Ruby.
The following guide will show you how to set up a free build environment on
[Travis][0], with [GitHub][1] integration for pull requests. Paid
alternatives exist for private repositories.
Continuous Integration (CI) enables you to publish your Jekyll generated website with confidence by automating the quality assurance and deployment processes. You can quickly get started using CI with one of the providers below:
[0]: https://travis-ci.org/
[1]: https://github.com/
## 1. Enabling Travis and GitHub
Enabling Travis builds for your GitHub repository is pretty simple:
1. Go to your profile on travis-ci.org: https://travis-ci.org/profile/username
2. Find the repository for which you're interested in enabling builds.
3. Click the slider on the right so it says "ON" and is a dark grey.
4. Optionally configure the build by clicking on the gear icon. Further
configuration happens in your `.travis.yml` file. More details on that
below.
## 2. The Test Script
The simplest test script simply 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][2].
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: `./script/cibuild`
### The HTML Proofer Executable
```sh
#!/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:
```sh
$ bundle exec htmlproofer ./_site --disable-external
```
### The HTML Proofer Library
You can also invoke `html-proofer` in Ruby scripts (e.g. in a Rakefile):
```ruby
#!/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,
check out `html-proofer`'s README file.
[2]: https://github.com/gjtorikian/html-proofer
## 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](https://docs.travis-ci.com/user/languages/ruby/#Dependency-Management) the dependencies based on the referenced gems:
```ruby
source "https://rubygems.org"
gem "jekyll"
gem "html-proofer"
```
Your `.travis.yml` file should look like this:
```yaml
language: ruby
rvm:
- 2.2.5
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
sudo: false # route your build to the container-based infrastructure for a faster build
```
Ok, now for an explanation of each line:
```yaml
language: ruby
```
This line tells Travis to use a Ruby build container. It gives your script
access to Bundler, RubyGems, and a Ruby runtime.
```yaml
rvm:
- 2.2.5
```
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.
```yaml
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.
```yaml
script: ./script/cibuild
```
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 `script`
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:
```yaml
install: gem install jekyll html-proofer
script: jekyll build && htmlproofer ./_site
```
The `script` directive can be absolutely any valid shell command.
```yaml
# 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.
The `branches` directive is completely optional. Travis will build from every
push to any branch of your repo if leave it out.
```yaml
env:
global:
- NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer
```
Using `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
environment variable `NOKOGIRI_USE_SYSTEM_LIBRARIES` to `true`.
<div class="note warning">
<h5>Be sure to exclude <code>vendor</code> from your
<code>_config.yml</code></h5>
<p>Travis bundles all gems in the <code>vendor</code> directory on its build
servers, which Jekyll will mistakenly read and explode on.</p>
<div style="display:flex;flex-wrap:wrap;">
<div style="width:49%;text-align:center;">
<a href="travis-ci/">
<img src="{{site.baseurl}}/img/travis-ci-badge.png" style="width:70%;" />
<h2>Travis CI</h2>
</a>
</div>
<div style="width:49%;text-align:center;">
<a href="circleci/">
<img src="{{site.baseurl}}/img/circleci-badge.svg" style="width:70%;" />
<h2>CircleCI</h2>
</a>
</div>
</div>
```yaml
exclude: [vendor]
```
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](https://docs.travis-ci.com/user/workers/container-based-infrastructure/#Routing-your-build-to-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
does need `sudo` access, modify the line to `sudo: required`.
```yaml
sudo: false
```
### Troubleshooting
**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.
### Questions?
This entire guide is open-source. Go ahead and [edit it][3] if you have a
fix or [ask for help][4] if you run into trouble and need some help.
[3]: https://github.com/jekyll/jekyll/edit/master/docs/_docs/continuous-integration.md
[4]: https://jekyllrb.com/help/

92
docs/_docs/continuous-integration/circleci.md Normal file
View File

@ -0,0 +1,92 @@
---
title: "CircleCI"
---
Building, testing, and deploying your Jekyll-generated website can quickly be done with [CircleCI][0], a continuous integration & delivery tool. CircleCI supports [GitHub][1] and [Bitbucket][2], and you can get started for free using an open-source or private repository.
[0]: https://circleci.com/
[1]: https://github.com/
[2]: https://bitbucket.org/
## 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: <https://circleci.com/add-projects>
1. From the GitHub or Bitbucket tab on the left, choose a user or organization.
1. Find your project in the list and click 'Build project' on the right.
1. The first build will start on its own. You can start telling CircleCI how to build your project by creating a [circle.yml][3] file in the root of your repository.
[3]: https://circleci.com/docs/configuration/
## Dependencies
The easiest way to manage dependencies for a Jekyll project (with or without CircleCI) is via a [Gemfile][4]. You'd want to have Jekyll, any Jekyll plugins, [HTML Proofer](#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`:
[4]: http://bundler.io/gemfile.html
```yaml
source 'https://rubygems.org'
ruby '2.4.0'
gem 'jekyll'
gem 'html-proofer'
```
CircleCI detects when `Gemfile` is present is will automatically run `bundle install` for you in the `dependencies` phase.
## Testing
The most basic test that can be run is simply 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.
```
dependencies:
post:
- 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][5] is popular amongst Jekyll users. We'll run it in the `test` phase with a few preferred flags. Check out the `html-proofer` [README][6] for all available flags, or run `htmlproofer --help` locally.
[5]: https://github.com/gjtorikian/html-proofer
[6]: https://github.com/gjtorikian/html-proofer/blob/master/README.md#configuration
```yaml
test:
post:
- bundle exec htmlproofer ./_site --check-html --disable-external
```
## Complete Example circle.yml File
When you put it all together, here's an example of what that `circle.yml` file could look like:
```
machine:
environment:
NOKOGIRI_USE_SYSTEM_LIBRARIES: true # speeds up installation of html-proofer
dependencies:
post:
- bundle exec jekyll build
test:
post:
- bundle exec htmlproofer ./_site --allow-hash-href --check-favicon --check-html --disable-external
deployment:
prod:
branch: master
commands:
- rsync -va --delete ./_site username@my-website:/var/html
```
## Questions?
This entire guide is open-source. Go ahead and [edit it][7] if you have a fix or [ask for help][8] if you run into trouble and need some help. CircleCI also has an [online community][9] for help.
[7]: https://github.com/jekyll/jekyll/edit/master/docs/_docs/continuous-integration/circleci.md
[8]: https://jekyllrb.com/help/
[9]: https://discuss.circleci.com

230
docs/_docs/continuous-integration/travis-ci.md Normal file
View File

@ -0,0 +1,230 @@
---
title: "Travis CI"
---
You can easily test your website build against one or more versions of Ruby.
The following guide will show you how to set up a free build environment on
[Travis][0], with [GitHub][1] integration for pull requests.
[0]: https://travis-ci.org/
[1]: https://github.com/
## 1. Enabling Travis and GitHub
Enabling Travis builds for your GitHub repository is pretty simple:
1. Go to your profile on travis-ci.org: https://travis-ci.org/profile/username
2. Find the repository for which you're interested in enabling builds.
3. Click the slider on the right so it says "ON" and is a dark grey.
4. Optionally configure the build by clicking on the gear icon. Further
configuration happens in your `.travis.yml` file. More details on that
below.
## 2. The Test Script
The simplest test script simply 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][2].
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: `./script/cibuild`
### The HTML Proofer Executable
```sh
#!/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:
```sh
$ bundle exec htmlproofer ./_site --disable-external
```
### The HTML Proofer Library
You can also invoke `html-proofer` in Ruby scripts (e.g. in a Rakefile):
```ruby
#!/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,
check out `html-proofer`'s README file.
[2]: https://github.com/gjtorikian/html-proofer
## 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](https://docs.travis-ci.com/user/languages/ruby/#Dependency-Management) the dependencies based on the referenced gems:
```ruby
source "https://rubygems.org"
gem "jekyll"
gem "html-proofer"
```
Your `.travis.yml` file should look like this:
```yaml
language: ruby
rvm:
- 2.2.5
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
sudo: false # route your build to the container-based infrastructure for a faster build
```
Ok, now for an explanation of each line:
```yaml
language: ruby
```
This line tells Travis to use a Ruby build container. It gives your script
access to Bundler, RubyGems, and a Ruby runtime.
```yaml
rvm:
- 2.2.5
```
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.
```yaml
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.
```yaml
script: ./script/cibuild
```
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 `script`
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:
```yaml
install: gem install jekyll html-proofer
script: jekyll build && htmlproofer ./_site
```
The `script` directive can be absolutely any valid shell command.
```yaml
# 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.
The `branches` directive is completely optional. Travis will build from every
push to any branch of your repo if leave it out.
```yaml
env:
global:
- NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer
```
Using `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
environment variable `NOKOGIRI_USE_SYSTEM_LIBRARIES` to `true`.
<div class="note warning">
<h5>Be sure to exclude <code>vendor</code> from your
<code>_config.yml</code></h5>
<p>Travis bundles all gems in the <code>vendor</code> directory on its build
servers, which Jekyll will mistakenly read and explode on.</p>
</div>
```yaml
exclude: [vendor]
```
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](https://docs.travis-ci.com/user/workers/container-based-infrastructure/#Routing-your-build-to-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
does need `sudo` access, modify the line to `sudo: required`.
```yaml
sudo: false
```
### Troubleshooting
**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.
### Questions?
This entire guide is open-source. Go ahead and [edit it][3] if you have a
fix or [ask for help][4] if you run into trouble and need some help.
[3]: https://github.com/jekyll/jekyll/edit/master/docs/_docs/continuous-integration/travis-ci.md
[4]: https://jekyllrb.com/help/

14
docs/img/circleci-badge.svg Normal file
View File

@ -0,0 +1,14 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Generator: Adobe Illustrator 19.1.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
viewBox="0 0 1000 1000" enable-background="new 0 0 1000 1000" xml:space="preserve">
<rect x="-3850" y="-1178" display="none" fill="#FFFFFF" width="700" height="700"/>
<g>
<path id="mark_1_" fill="#FFFFFF" d="M373.4,500c0-65.8,53.3-119.1,119.1-119.1c65.7,0,119,53.3,119,119.1c0,65.7-53.3,119-119,119
C426.8,619,373.4,565.7,373.4,500z M492.5,0C259.1,0,63.3,159.9,8.1,376.1c-0.4,1.6-0.6,3.2-0.6,4.8c0,13.2,10.7,23.8,23.8,23.8
h201.5c9.6,0,17.8-5.7,21.6-13.9l0.1,0c41.4-90.1,132.4-152.8,238-152.8c144.6,0,261.9,117.3,261.9,261.9
c0,144.6-117.3,261.9-261.9,261.9c-105.7,0-196.7-62.6-238-152.8l-0.1,0c-3.8-8.2-12-13.9-21.6-13.9H31.3
c-13.1,0-23.8,10.7-23.8,23.8c0,1.6,0.3,3.2,0.6,4.8C63.2,840,259.1,1000,492.5,1000c276.1,0,500-223.9,500-500
C992.5,223.9,768.6,0,492.5,0z"/>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.0 KiB

BIN
docs/img/travis-ci-badge.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB