【GitLab 公式 を訳してみた】ウェブサイトで必要な「.gitlab-ci.yml」設定

法律: IT 解説記事 GitLab CI GitLab コンテナ ウェブ制作 アプリ フノス(訳者) マニュアル

  GitLab DocumentationUser documentationProjectsGitLab Pages 説明書>ウェブサイトで必要な「.gitlab-ci.yml」設定

この記事は、Marcia Ramos が2017年2月22日に発表したものを、2018年2月16日に更新したものです。種類:ユーザーガイド・レベル:中級

  GitLab CIサーバーは、アプリの継続的インテグレーションにおける、あらゆる工程を実行します。ビルド、テスト、デプロイ、これらの作業をCIサーバーに担わせることができます。
 GitLab Pagesも「ウェブサイト」という、1種のアプリとして捉えることが可能です。ビルドしたウェブサイトは、専用のPagesサーバーにデプロイすることになります。

  さて、ようやく GitLab CI/CDを実装するには、ウェブサイトの rootディレクトリに「.gitlab-ci.yml」設定ファイルを作成する必要があります。

  このファイルには、GitLab ランナーに実行してもらうスクリプトを記述します。元々はあなたがコマンドラインから出していた指示を、このファイルに記録してしまうのです。
 ここでいうランナーは、皆さんがお使いのターミナルのような役割を果たします。GitLab CI/CD は、ファイルの中身を読み取って、ランナーにコマンドを出す部分です。
 CI/CDもランナーも、どちらもGitLabに備え付けてあるものなので、動作させるために利用者が何かの設定する必要はありません。

  GitLab ランナー と GitLab CIの詳しい説明につきましては、このページでは触れません。その代わり、「.gitlab-ci.yml」ファイルを設定する上で、押さえてもらいたいポイントを以下にまとめました。
「.gitlab-ci.yml」設定ファイルは、Yamlファイルである。よって、yamlシンタックスで記述する。
CI シンタックスが正しいかどうかは、GitLab CI Lint ツールを使って判定する。

 

  実施例

  それでは、最も代表的な静的サイトジェネレータである、Jekyllを使ったサイトの設定ファイルの作り方を紹介します。
 まずローカル環境でJekyllサイトをビルドするには、ターミナル開いて「jekyll build」というコマンドを入れるのが普通でしょう。もちろん、ビルドに入る前には、皆さんのコンピューターには Jekyllをインストールしておかなくてはなりません。
 Jekyllのコード言語はgemなので、「gem install jekyll」というコマンドを使います。ここまでは良いですか?

 GitLab CI + GitLab Runner にも、まるで同じ指示を出します。「.gitlab-ci.yml」にビルドなどに必要とされるスクリプトを、全部記述してください。GitLabランナーはその通りに動作するでしょう。

 もう一度、Jekyllをビルドする上で核となるコマンドを確認します。
 これから肉付けしていく要素に気を取られてしまいそうになりますが、これらは絶対外せません。

======================
$ gem install jekyll

$ jekyll build
====================== 

 

  Script

  上のコマンドをYaml書式に変換すると、次の通りになります。

======================
script:
 - gem install jekyll
 
- jekyll build
======================
 

  Job

  たった上の設定だけでも、ランナーは動くと言えば動くんです。
 でも、実際は、それぞれのscriptたちに、jobという単位を設けて、タスクごとに分類してないと後が大変です。

======================
job:
 script:
  - gem install jekyll
 
 - jekyll build
====================== 

  さらに、GitLab Pagesをビルドする時には、job名を「pages」としなくてはなりません。「pages」という記号が、ランナーにとっては、GitLab Pages(ウェブサイト)をデプロイする合図になっています。

 ======================
pages:
 script:
  - gem install jekyll
  
- jekyll build
====================== 

 

  public ディレクトリ

  job名を「pages」にしただけでは、ウェブサイトは出来上がりません。なぜなら、ウェブサイトをビルドするディレクトリを指定しないからです。
 GitLab Pagesで、そのディレクトリに指定できるのは、「public」ディレクトリのみです。
 "どこにビルドするか"を指定するには、jekyll buildの後に、(-d)でディレクトリを指定します。(つまり「website: jekyll build -d public」)

======================
pages:
 script:
  - gem install jekyll
  
- jekyll build -d public
====================== 

 

  ビルド物の置き場指定

  さっき、ランナーにビルドをする場所を教えましたが、ビルドしたあとの物(artifacts)をどこにやるかを指定していません。
 もちろん、publicディレクトリと指定しないと、サイトが出来上がりません。job名がpagesという時点で、置く場所は殆ど決まっているのにねえ。

 ======================
pages:
 script:
  - gem install jekyll
 
 - jekyll build -d public
  
artifacts:
   paths:
    - public
======================

  以上のスクリプトさえあれば、JekyllサイトをGitLab Pagesでビルドするには十分です。

 しかし、Jekyll 3.4.0以降からは、開発プロジェクトの方針で、依存関係のインストールに Bundlerを使うようになりました。Jekyllのインストールとデフォルトテーマの導入には、Bundlerが必要です。
 上のスクリプトを次の通りに変換します。scriptの部分にだけ変更があって、「public」をサイトのディレクトリに指定することに変わりはありません。
 

======================
pages:
 script:
  - bundle install
  - bundle exec jekyll build -d public
  artifacts:
   paths:
    - public
====================== 

   Jekyll 3.4.0で作成するサイトは、この設定でビルド可能です。
 以上!最低限、この設定だけはしなくてはならないものを紹介しました。
 力作の「.gitlab-ci.yml」が、何故か動かないときには、この最も基本的な設定に抜け・漏れがないかを確認してください。
 

  ちなみに、Artifactsはサーバーがウェブサイトを立ち上げるために使う簡易キットみたいなものです。GitLab Pagesにウェブサイトがデプロイされると、自動的に削除されます。保存期間を指定しておくと、その期間だけはArtifactsが消去されないように変更できます。

 

  Image

  設定ファイルには、サイトジェネレータと依存関係にあるソフトを入れるコマンドを記述しなくてはならりません。
 「確かその筈…、あらら?Rubyのインストールはどうしたの?そのスクリプトどうやって書くの?」
 覚えてしまえば簡単です。最初に「image: 」パラメータを使います。
 ライブラリを導入するときは、scriptではなく、imageに記述したほうが、ビルドが安定します。
 これはランナーに 、Dockerイメージを用意させて、その中でscriptを実行させる方法です。

======================
image: ruby:2.3

pages:
 script:
  - bundle install
  
- bundle exec jekyll build -d public
  artifacts:
   paths
:
    - public
====================== 

  この場合に、ランナーが引き出してくるDockerイメージは、Ruby 2.3が、ファイルシステムの一部として導入されているコンテナです。

「じゃあ、さっきの設定は image: を指示していなかったのに、どうしてうまくいったの?」
と疑問に思う方もいらっしゃるでしょう。
 実は、GitLabではビルドに使用するコマンド(gem, bundleなど)に応じて、デフォルトで使用するイメージが定められています。
 たとえば、Ruby系のコマンドなら、Ruby 2.1 が入ったイメージが、自動適用されます。
 

  ただし、NodeJS がビルドの際に必要な静的サイトジェネレータについては、NodeJSのバージョンを必ず image: で指示しなくてはなりません。ファイルシステムの中に、ジェネレータに当てはまるライブラリが入っていないと、ビルドが失敗します。
 例:Hexoサイトのビルドには、image: node:4.2.2 が必要。
 

 注:どのDockerイメージを使えばよいか不明なら、「最低限これだけは必要そう」というイメージを選びましょう。このような時に、Dockerイメージについて、ある程度の知識があると便利です。イメージについての説明が書かれているサイトを見ましょう。こちらの記事も参考になります。

 


  コマンドをscriptにすることと、ライブラリをimageで揃えるところまでが、「.gitlab-ci.yml」の基本です。
 次はもう少し込み入った設定まで行ってみましょう。


 

  ブランチわけ

  GitLabをバージョン管理ソフトとして使っている方なら、プロジェクトにブランチをつけることが当たり前のようになっていることでしょう。大抵のプロジェクトなら、同じプロジェクトでもブランチごとに、少し違った開発をすることが多いものです。

 しかし、ウェブサイトの場合は、デフォルト・ブランチ(たいてい master)だけにプッシュした方が良いでしょう。
  pagesに書かれたスクリプトが、誤って動作するリスクを減らすためには、「only: -master」と設定して、ウェブサイトプロジェクトのmasterブランチにプッシュがあったときにだけ、ランナーを動かすように設定してください。

======================
image: ruby:2.3

pages:
 script:
  - bundle install
  
- bundle exec jekyll build -d public
  artifacts:
   paths:
    - public
   only:
    - master
====================== 

 

  Stages

  今までの設定は、すべて「build」ステージの工程であることを念頭に置いておくと、設定のバリエーションを広げられます。ウェブアプリの開発なら、たくさんのテストを通してから、デプロイすることになりますが、それらの工程を大まかにタグ付けすることで、ランナーにより多くの作業を任せられます。
 「stages:」パラメータでは、デフォルトで、build, test, deployの3つのタグが用意されています。現在のjob(ここではpages:)が、今どの工程に属しているかを、CIに読み取らせる記号です。

======================
image: ruby:2.3

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

  「ウェブサイトもアプリの一種なんでしょ。だったら、test用のjobを設けることもできる?」と考えられたなら、あなたは鋭い。

 できますよ。「stages: -test」と書かれているjobさえあれば、サイトをデプロイする前に、何らかのバグ検閲テストをかけられます。

 masterブランチにプッシュする前に、scriptにテストのコマンドを入れたい場合、
masterブランチ以外(exept: -master)にプッシュがされたら、テスト用のjobが作用するような、
タスク(job)をもう1つ追加すれば良いのです。

======================
image: ruby:2.3

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


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

  新たに追加された「test」jobは、Jekyllサイトを testディレクトリにビルドします。masterブランチでないところにプッシュすれば、必ず作用するように設定しました。

  この先、test jobに新たな項目を追加すれば、stage buildとは違ったjobにしていけるようになったというところで、前のコンフィグと大きく差が付いたのではないでしょうか。
 もし、デプロイ前にさらなる試験が必要そうなら、他のテストも追加するとよいでしょう。アプリのテストは、1つのテストが終了しなければ、他のテストができないわけではありません。このjobに記述したテストは、すべて同時に実行することができます。
 「stage」によるjobの分類のさわりは、これでよいでしょう。他のCIツールでも同じような機能があるはずです。とてもよいテストツールを知っているのなら、このようにstage分けをしたほうが効果的ですが、GitLab Pagesでサイトを作る分には、このあたりの設定はほどほどでよいのではないでしょうか。

 

  Before Script

  jobが複数個になりました。すると、それぞれのjobに「bundle install」というコマンドがあることになります。

 それぞれのjobは同時に作動させることが可能です。そのときにあちこちのjobで、同じコマンドを一斉に使い始める現象が起こってしまうことがあります。こうなると、ランナーにもそれなりに負荷がかかります。
 これを避けるために、「複数のjobで使用するコマンドを、1つのjobとして扱ってしまう」方が、機械にとって都合が良いわけです。

 そこで、両方のjobにある、「bundle install」というコマンドに、「before_script:」というjobを設けて、ランナーに2度手間を負わせない設定にします。

======================
image: ruby:2.3

before_script:
 - bundle install

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


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

 

  キャッシュがけ

  ビルドの時間を短縮したかったら、プロジェクトと依存関係にあるバイナリなどに、キャッシュをかけるとよいでしょう。そこで使われるのが「chache」パラメータです。

 この例では、Jekyllの依存関係である「bundle install」にキャッシュを設けています。キャッシュを使うには、まずキャッシュを置くディレクトリをきちんと指定しなくてはなりません。ここでは「vendor/」ディレクトリとなっています。

======================
image: ruby:2.3

cache:
  paths:
   - vendor/

before_script:
 - bundle install

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


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

  まだ、Jekyllサイトを作るのは待ってください。ここで設定したのは、ランナーだけが使うキャッシュファイルなので、ビルドの時にだけ必要とされます。
 つまり、これは誤ってアプリの中に組み込まれてはならないものなのですが、Jekyllには、CI設定で提示されたファイルを、手当たり次第にアプリにしていく性質があります。

 「.gitlab-ci.yml」の設定が終わったら、次はJekyllの「_config.yml」を開いて次の設定をしてください。
 

======================
exclude:
 - vendor
======================
 

  さあ、プッシュしてみましょう。

 GitLab CIは、ウェブサイト(アプリ)をビルドするのが基本だとして、ブランチわけ、キャッシュがけ(ここではbundleにかけた。)、その他特殊なjobを追加するような、応用技をかけられます。
 masterブランチにプッシュがなされれば、すぐさまデプロイが始まります。

 

  GitLab Pagesに GitLab CIで さらに工夫を凝らす

  ざっと覚えてほしい項目は、以上の通りですが、GitLab CIには、まだまだ皆さんのクリエイティビティを後押しする機能があります。スクリプトの組み立て次第で、上手に使えば、今まで手作業だった工程を殆ど自動化できますよ。
 GitLab CIで使えるパラメータは、こちらの記事に掲載されていますので、その中から「これいいかも」というものを足していってください。

 2018-05-16 01:01:34 / Hnoss
原文サイトを表示
[ 原文 ] https://docs.gitlab.com/ee/user/project/pages/getting_started_part_four.html
原文ページプロジェクト並びにドキュメントファイルは、MIT Licenseのもと公開されています。(URL:https://gitlab.com/gitlab-com/gitlab-docs/blob/master/LICENSE) この記事の文章は、訳者の判断によりCreative Commons BY (version 3.0) を適用するものとします。