Travis CI

Webサイトのビルドを1つ以上のバージョンのRubyに対してテストできます。次のガイドでは、プルリクエスト用のGitHub統合を使用して、Travisで無料ビルド環境を設定する方法を説明します。

1. TravisとGithubの有効化

GitHubリポジトリのTravisビルドを有効にします。

travis-ci.orgのあなたのプロフィールへ行きます：https://travis-ci.org/profile/username
ビルドを有効にしたいリポジトリを見つけます。
リポジトリスイッチをオンにして、青色にします。
歯車アイコンをクリックしてビルドのうプション設定ができます。それ以上の設定は.travis.ymlファイルで行います。詳細は下記をご覧ください。

2. テストスクリプト

最も単純なテストスクリプトはjekyll buildを実行し、Jekyllがサイトの構築に失敗しないことを確認します。結果のサイトは確認しませんが、物事が適切に構築されていることは確認します。

Jekyllの出力をテストするには、html-prooferが最も良いツールです。このツールは結果のサイトをチェックして、すべてのリンクと画像が存在することを確認します。便利なhtmlprooferコマンドライン実行ファイルでそれを利用するか、あるいはgemを利用するRubyスクリプトを書いてください。

実行したい成功したコマンドを./script/cibuildファイルに保存します。

The HTML Proofer Executable

#!/usr/bin/env bash
set -e # halt script on error

bundle exec jekyll build
bundle exec htmlproofer ./_site

一部のオプションはコマンドラインスイッチで指定できます。これらのスイッチの詳細については、html-prooferのREADMEを確認するか、htmlproofer --helpをローカルで実行してください。

外部のサイトをテストを避ける上記の例は、以下のコマンドを使用します。

bundle exec htmlproofer ./_site --disable-external

The HTML Proofer Library

Rubyスクリプト（Rakefileなど）でhtml-prooferを呼び出すこともできます。

#!/usr/bin/env ruby

require 'html-proofer'
HTMLProofer.check_directory("./_site").run

オプションは.newの2番目の引数として与えられ、シンボルキー付きのRuby Hashでエンコードされています。設定オプションの詳細については、html-prooferのREADMEファイルをご覧ください。

3. Travisビルドの設定

このファイルはTravisビルドを設定するために使用されます。JekyllはRubyでビルドされており、インストールにはRubyGemsが必要なので、Ruby言語ビルド環境を使います。以下はサンプルの.travis.ymlファイルで、その後に各行の説明が続きます。

注：Gemfileも必要です。Travisは参照されているgemに基づいて依存関係を自動的にインストールします。こちらは、2つの参照gem、”jekyll”と”html-proofer”を持つGemfileです。

source "https://rubygems.org"

gem "jekyll"
gem "html-proofer"

.travis.ymlは次のようにします。

language: ruby
rvm:
  - 2.6.3

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

cache: bundler # caching bundler gem packages will speed up build

# Optional: disable email notifications about the outcome of your builds
notifications:
  email: false

それでは、各行について説明します。

language: ruby

この行は、TravisにRubyビルドコンテナを使用することを伝えます。Bundler、RubyGems、Ruby runtimeへのアクセスを与えます。

rvm:
  - 2.6.3

RVMは（rbenv、chrubyのように）有名なRubyのバージョン管理です。これはTravisにテストスクリプトを実行するときに使うRubyのバージョンを伝えます。ビルドをスピードアップするためにTravisビルドドッカーイメージにプレインストールされているバージョンを使用してください。

before_script:
 - chmod +x ./script/cibuild

ビルドスクリプトファイルには実行可能属性を設定する必要があります。そうしないと、Travisはパーミッション拒否エラーで失敗します。これをローカルで実行して権限を直接コミットすることもでき、このステップは無関係です。

script: ./script/cibuild

Travisはあなたのサイトをテストするために任意のシェルスクリプトを実行することを可能にします。1つの規則は、プロジェクトのすべてのスクリプトをscriptディレクトリに置き、テストスクリプトをcibuildと名付けます。この行は完全にカスタマイズ可能です。スクリプトがそれほど変わらない場合は、テストの呪文をここに直接記述できます。

install: gem install jekyll html-proofer
script: jekyll build && htmlproofer ./_site

scriptディレクティブは、絶対に任意の有効なシェルコマンドにすることができます。

# branch whitelist, only for GitHub Pages
branches:
  only:
  - gh-pages     # test the gh-pages branch
  - /pages-(.*)/ # test every branch which starts with "pages-"

サイト用のTravisビルドがサイトを含むブランチでのみ実行されていることを確認します。この分離を確実にする1つの方法は、Travis設定ファイルにブランチホワイトリストを含めることです。gh-pagesブランチを指定することで、関連するテストスクリプト（上記で説明）がサイトブランチでのみ実行されるようになります。変更を提案するためにプルリクエストフローを使用する場合は、上記の/pages-(.*)/正規表現で例証されているように、編集を含むすべてのブランチにプレフィックスを付けるように、ビルドを強制することができます。

branchesディレクティブは完全にオプションです。省略した場合、Travisはリポジトリの任意のブランチへのすべてのプッシュから構築します。

env:
  global:
  - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer

html-prooferを使用していますか？　この環境変数を必要とするでしょう。NokogiriはコンパイルされたサイトでHTMLファイルを解析するのに使われ、それがインストールされるたびにコンパイルされなければならないライブラリにバンドルされています。幸いなことに、環境変数NOKOGIRI_USE_SYSTEM_LIBRARIESをtrueに設定することによって、Nokogiriのインストール時間を劇的に減らすことができます。

`_config.yml`から`vendor`を除外してください

Travisはビルドサーバー上のvendorディレクトリの全gemをバンドルしています。Jekyllが間違えて読んで爆発します。

exclude: [vendor]

ビルドをスピードアップするために、bundlerによって作成されたgemパッケージをキャッシュするべきです。Travisは事前定義されたツールのキャッシュストラテジーを持っています。正確にするためにすべてのデフォルト設定が必要です。

cache: bundler

オプションで、ビルドEメール通知が必要ない場合は、この構成でそれらを無効にすることができます。Travisはさまざまな通知サービスをサポートしており、（slackなど）別の役立つサービスを見つけることができるでしょう。

notifications:
  email: false

トラブルシューティング

Travis error: “Gemfileを変更した後でデプロイモードをインストールしようとしています。他の場所でbundle installを実行し、更新されたGemfile.lockをバージョン管理に追加してください。”

Workaround: bundle installをローカルで実行してGemfile.lockへの変更をコミットするか、Gemfile.lockファイルをリポジトリから削除して.gitignoreファイルにエントリを追加して、再度チェックインされないようにしてください。

疑問がありますか？

このガイド全体はオープンソースです。修正がある場合は先に進んで編集し、問題が発生して助けが必要な場合は助けを求めてください。