Hnoss

Hnoss

今さらながら題名間違いに気がづいて、大量修正を加えたところ。
カレンダー

文書タグ

フノス(訳者)(142) IT(114) 解説記事(69) オープンソース(49) メディア(31) Linux(30) ウェブ制作(23) GitLab CI(21) DTM(19) HTML5(19) Libre Music(18) おすすめ オープンソース・ソフトウェア(17) 百科事典(14) プラグイン(13) 文化(12) コンテナ(12) ソフトウェア(11) 録音(11) ミキシング(11) MIDI(10) 西アジア/中東(10) 東ヨーロッパ(9) 料理(9) ジョージア(9) グルジア(9) セキュリティ(8) シーケンス(8) 芸能(8) 音楽編集(8) 音楽(7) マスタリング(7) 経済(6) WordPress(5) アプリ(5) 業務効率化(5) JACK(5) コマンド(5) Google(4) 映像制作(4) Android(4) 音楽プレーヤー(4) マイクロサービス(4) アニメーション(3) IoT(3) Ardour(3) 社会(3) Windows(3) Java(3) ワークフロー(3) ソーシャルメディア(3) GNU(3) DAW(3) 欧州(3) Ubuntu(3) Python(3) 北米(3) アニメ(3) ホームオートメーション(3) GNOME3(2) 歴史(2) 仮想通貨(2) マーケティング(2) PlayStation(2) 古代エジプト(2) 有角神(2) ERPシステム(2) 電子ブック(2) エジプト(2) ALSA(2) OS X(2) トヨタ(2) Krita(2) 電子書籍(2) ERP(2) バト(2) ウィッカ(2) Twitter(2) GPL(2) オカルト(2) ロスレス音源(2) スマホ(2) 牛(2) ニュース(2) 由来(1) グンデストルップの大釜(1) カナン(1) カナダ(1) 詩篇(1) チップチューン(1) バ・ネブ・デデト(1) コットン・マザー(1) クラウドキャスティング(1) VST(1) リーナス・トーバルズ(1) エリファス・レヴィ(1) マサチューセッツ(1) 考古学(1) 申命記(1) スタジオジブリ(1) クヌム(1) 魔女裁判(1) オンデマンド(1) 政治(1) バフォメット(1) 国際(1) クリエイティブ・コモンズ(1) 黙示録(1) Synfig(1) 独占(1) アモン(1) セイラム魔女裁判(1) ねじ巻きラジオ(1) 3D(1) EU(1) イボ人(1) 国際公文書館会議(1) マイナビ(1) キリスト教(1) レビ記(1) アマナイ(1) 広告(1) KXStudio(1) 絵文字(1) サンフランシスコ(1) イケンガ(1) リクルート(1) ユダヤ教(1) ウルガタ聖書(1) 科学技術(1) Blender(1) 出エジプト記(1) 観光案内(1) ツイッター(1) Youtube(1) パキスタン(1) CC(1) ハトホル(1) パン(1) 地方(1) 羊神(1) ギリシャ(1) 高速道路情報無線(1) ゲーム(1) 法律(1) 中南米(1) モヘンジョ=ダロ(1) 悪魔(1) ラジオ(1) OpenToonz(1) 電子教材(1) アレクサンドロス大王(1) ローマ(1) ポッドキャスト(1) パシュパティ(1) アピス(1) 宗教(1) テレビ(1) BountySource(1) 船乗りの柱(1) シリア(1) GPS(1) 日記(1) アフリカ(1) リグ・ヴェーダ(1) F-Droid(1) 教育(1) bi-modal IT(1) ムネヴィス(1) ネオペイガニズム(1) コミュニティ放送(1) アンビソニック(1) Papagayo(1) 写真(1) 元ネタ(1) ケルヌンノス(1) ナイジェリア(1) iOS(1) 聖書(1) 任天堂 DS(1) 学校(1) 日本(1) 魔女宗(1) アクティブSETI(1) バイノーラル(1) アップストリーム・パッケージング(1) 画像(1) 意味(1) コシディウス(1) インド(1) ユーコン(1) サウンドフォント(1) ヤーウェ(1) CD(1) タブレット(1) 羊(1) ベルゼブブ(1) デジタルサイネージ(1) VR(1) ポータブルソフトウェア(1)
リファレンス

first-time visitors
user guide
謝辞

「みんなの翻訳」は情報通信研究機構言語翻訳グループ東京大学図書館情報学研究室による共同プロジェクトであり、三省堂国立情報学研究所連想情報学研究開発センターが開発に協力しています。三省堂には「グランドコンサイス英和辞典(36万項目収録)」の使用を許可していただきました。

連携研究グループはこちらをご覧ください。

「みんなの翻訳」を使っている翻訳グループについてはこちらをご覧ください。

バナー

logo

ポスター

poster

フライヤー

poster poster
Mozilla Firefox ブラウザ無料ダウンロード
本サイトはブラウザ「Mozilla Firefox」推奨です。
Firefox3で動作確認しています。

Valid XHTML 1.0 Transitional

site_image
Configuration of your jobs with .gitlab-ci.yml
https://docs.gitlab.com/ee/ci/yaml/README.html
Hnoss Hnoss     最終更新:2017-11-17 23:50:27    PDF


 (訳者より:翻訳がもうだいぶ進んだところで、GitLab CIについてネットで検索をかけてみたところ、Qiitaにてynott様が公開されたバージョンがあることに気がつきました。
 原文ページを拝見いたしましたところ、ynott様がce版、私がee版と、少しページが異なるようです。
 しかし…内容はだいたい同じですね。 
 日付を見る限り、ynott様の方は「2017/09/17に投稿」「2017年10月02日更新」とありますので、あちらの方が先輩です。
 「あちゃー。訳す前に調べておくんだった」とも思ったのですが、せっかくです。自分なりに全訳してみることにしました。
 あくまで私としては「訳してみた」だけなので、こちらはHnossバージョンということで、よろしくお願いします。)

 .gitlab-ci.ymlファイルの設定に使える項目には、色々な種類がありますが、このページではそれらの1つ1つの効果・役割を解説します。

 このファイルの簡単な使い方は、こちらのページに書いてありますので、そちらもご覧ください。


 .gitlab-ci.yml とは

 GitLab 7.12から、 GitLab CIを YAML形式( .gitlab-ci.yml)で設定できる機能が追加されました。
 このファイルをレポジトリのrootディレクトリに設置すると、ビルドの時にそこに設定した内容が自動で適用されます。

 このYAMLファイルには「job」というタスクのグループ設定します。「job」はタスクをまとめ上げた一番大きな塊のことで、その下には小さなスクリプトが配置されます。
 たとえば、

======================
job1:
  script: "execute-script-for-job1"

job2:
  script: "execute-script-for-job2"
======================

 たとえば、CI設定が2つのjobで構成されていた場合は、上のように2つのjobがYAMLファイルに記述されます。
 ここで大切なのは、それぞれのjobで実行されるスクリプトは同じものであってはならないことです。

 このスクリプトの部分にはコマンドをそのまま入れて構いません。(./configure;make;make installなど)
 また、レポジトリの中のスクリプトを実行させるのも便利でしょう。( test.shなど)

 設定したjobはランナーが検知し実行してくれます。
 なおかつ、この自動検知機能を使えば、それぞれのjobを状況に応じて、使い分けさせることも可能です。

 YAMLシンタックスなら、たくさんの設定を加えてもシンプルに見直すこともできるのです。
 たとえば、このような設定も。

======================
image: ruby:2.1
services:
  - postgres

before_script:
  - bundle install
after_script:
  - rm secrets

stages:
  - build
  - test
  - deploy

job1:
  stage: build
  script:
   - execute-script-for-job1
  only:
   - master
  tags:
   - docker
======================

 jobにはいくつか種類があり、その中には状況に特化しすぎてあまり有名でないものもあります。
 しかし場面によっては、大変役立つものでもあるので、以下の表を参考に開発にお役立てください。

jobの種類 必須か 説明
image no どのようなDockerイメージを使うかを指定する。 詳しくは Use Dockerへ。
services no どのようなDockerサービスを使うかを指定する。 詳しくは Use Dockerへ。
stages no ビルドの段階を指定する
types no stagesを別名に置き換える (非推奨)
before_script no それぞれのjobスクリプトの前にしなくてはならないコマンドを指定する
after_script no それぞれのjobスクリプトの後にしなくてはならないコマンドを指定する
variables no ビルドの変数を定義する
cache no キャッシュ。ビルドの最中などに何度も使用するファイルを指定するとよい

 image と services

 これらはDockerイメージやサービスのリストを指定する項目なのですが、これについては別の説明書で解説します。

 before_script

 jobをいくつも設定していると、どのjobを発動させる前にも、必要なコマンドが出る場合があります。
 それをこのjobに設定しておくと、後で1つ1つのjob設定が楽になります。複数のコマンドを設定できます。
 jobを展開している時に、いつも必要になるコマンドもこの項目に入れてください。
 ただし、ここで設定されたコマンドは、全てのjobが終了した後には発動されないことをお忘れなく。

 after_script

 GitLab 8.7以降に導入。Gitlab Runner v1.2以上が必要。

 全てのjobが発動しきった後に、動かす必要があるコマンドを入れます。複数設定可能。

 stages

 jobがどのタイミングで使われるかを指定する項目です。
 これを設定すると、jobをより多様に使い分けることができます。

 次の性質があります。

  1. 同じステージを設定されたjobが複数ある場合、それらは全て同時進行で動きだす
  2. 1つのステージが終了すると、すぐさま次のステージに移る



 ステージは主に3種類あります。

======================
stages:
  - build
  - test
  - deploy
======================
 そして、次のような動作をとります。

  1. まずbuildステージのjobが同時に発動する
  2. buildステージのjobが問題なく完了すると、testステージのjobが全て発動する
  3. testステージのjobが問題なく完了すると、deployステージのjobが全て発動する
  4. deployステージのjobが問題なく完了すると、今度はsuccessというマークが表示される
  5. jobの中にどれか1つでも成功しなかったものがあったら、そこから先のステージにあるjobは中止され、failedというマークが表示される

備考:

  1.  デフォルトの状態では、ステージはbuildtestdeployの順に実行される。
  2.  これといってステージを定義しなかったjobについては、testステージで実行されることになっている。


  types

 stagesにエイリアスを設ける項目ですが、使用は推奨できません。
 将来のリリースでは削除も検討している機能です。stagesを使ってください。

 variables 

 GitLab Runner v0.5.0以降に導入。

 jobを実行するための環境変数を設定します。
 また、ここに設定する変数をgitレポジトリに当てると何かと便利かもしれません。
 ただし、ちょっとの変更がどう出るか分からない複雑なプロジェクトでの使用は、慎重にしておいた方が良いでしょう。

======================
variables:
  DATABASE_URL: "postgres://postgres@postgres/my_database"
======================

 注:変数の部分に施す設定(整数)には、必ずや変数に一致するものを入れてください。変数にはストリングスの役割があります。この部分が間違っていると、使用することができません。

 変数は全てのコマンドやスクリプトが実行された後に使われるものがほとんどです。
 先に作っておいたサービスを全部ここに代入して、後からサービスの内容を微調整してもよいでしょう。
 jobごとに変数を設定することも可能ですが、その方法については後ほど説明いたします。

 変数のなかにはランナーに直接指示を与えるものも存在します。
 たとえば、CI_COMMIT_REF_NAMEには、特定のブランチやtag名を入れて、 どのプロジェクトをビルドするかを指定します。

  また、これらとは別にGitLabの UIを設定するための変数(秘密変数)もありますが、これは.gitlab-ci.yml内に記述するものではありません。

 変数についてはこちらのページで詳しく解説しています。

 cache

 GitLab Runner v0.7.0以降に導入。
 GitLab 9.2以前では、キャッシュはアプリを生成してから復元されるものだったものが、
 GitLab 9.2以降は、アプリを生成する前に復元されるよう仕様が変更されている。

 cacheには、たくさんのjobで使われるファイルやディレクトリを指定しておくとよろしいでしょう。
 設定はcacheの下にpathsを設けるだけですので、とても簡単です。

 GitLab 9.0では、デフォルトでキャッシュの使用が許可されており、pipelineや各job間でのキャッシュ共有が可能です。

 特定のjobに設定しなかったキャッシュは、全てのjobに適用されます。

 binaries.configにあるファイル全てにキャッシュをかける場合:

======================
rspec:
  script: test
  cache:
   paths:
   - binaries/
   - .config
======================

 全てのGit未追跡ファイルにキャッシュをかける場合:

======================
rspec:
  script: test
  cache:
   untracked: true
======================

 binariesファイルと、全てのGit未追跡ファイルにキャッシュをかける場合:

======================
rspec:
  script: test
  cache:
   untracked: true
   paths:
   - binaries/
======================

 ローカルに定義済みのキャッシュがあるので、それをプロジェクト全体に適用し、
 rspec
jobのキャッシュはbinaries/ファイルにだけ効かせる場合:

======================
cache:
  paths:
  - my/files

rspec:
  script: test
  cache:
   key: rspec
   paths:
   - binaries/
======================

 注:複数job間でキャッシュを共有する場合、もしもjobごとに異なるパスを使っているのなら、それはjobごとに別個で設定しなおした方がよいでしょう。
 しかし、場合によってはjobごとに異なるcache:keyを使うことで、キャッシュコンテンツを上書きできる可能性もあります。

 特にキャッシュは効果があれば目覚ましいものがあるので、つい期待も過ぎてしまいます。
 なので、どれが最も効果的かはGitLabランナーの様子を見ながら決めてくださいね。

 cache:key

 GitLab Runner v1.0.0以降に導入。

 キャッシュをかける範囲を、jobごと、ブランチごとに指定することができます。
 たとえば、全体としてはほとんどこのキャッシュで遭っているけれども、それに当てはまらないjobが1つだけある場合などは、これを使って例外を作ることができます。

 キャッシュの範囲を調整して、キャッシュのグループ分けをしてもよいでしょう。

 cache:keyには、すべての定義済み変数を代入することができます。

 デフォルトでのkeyの範囲は、プロジェクト全体です。
 パイプラインやジョブ間でのキャッシュ共有に支障がでないようにしてあります。
 GitLab 9.0から導入された、比較的新しい機能です。

 注:定義済み変数をchache:keyで利用するときには、「/」という文字を使うことができません。

 cash:key設定例

 jobごとにキャッシュをかける

======================
cache:
  key: "$CI_JOB_NAME"
  untracked: true
======================

 ブランチごとにキャッシュをかける

======================
cache:
  key: "$CI_COMMIT_REF_NAME"
  untracked: true
======================

 jobごと、ブランチごとにキャッシュをかける

======================
cache:
  key: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
  untracked: true
======================

 ブランチごと、stageごとにキャッシュをかける

======================
cache:
  key: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
  untracked: true
======================

 Windows Batchを使ってシェルスクリプトを動かしている場合は、 「$」を「%」に置き換えなくてはならない。

======================
cache:
  key: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
  untracked: true
======================

 Windows PowerShellでシェルスクリプトを動かしている場合は、「$」を「$env:」に置き換えなくてはならない。

======================
cache:
  key: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
  untracked: true
======================

 cache:policy

 GitLab 9.4以降に導入。

 jobにキャッシュをかけた場合、通常はjobを実行する前に 、指定されたファイルをダウンロードしてします。
 そして、jobが終了すると、キャッシュファイルを復元してから再アップロードするようになっています。
 jobはこれらの動作を延々と繰り返しているのですが、これにも名前がありまして「pull-pushキャッシュポリシー」といいます。

 通常、jobはキャッシュファイルの内容までもを書き換えることはできません。なのでjobにキャッシュファイルをアップロードし直す手間を省略させたところで、これといった問題はありません。
 この動作を実現するのが、「policy: pull」という項目です。
 なおかつ、この設定にしておくと、jobがキャッシュファイルをビルドの早い段階から読み込み、常に最新の情報に更新するようになります。

======================
stages:
  - setup
  - test

prepare:
  stage: setup
  cache:
   key: gems
   paths:
    - vendor/bundle
  script:
   - bundle install --deployment
rspec:
  stage: test
  cache:
   key: gems
   paths:
    - vendor/bundle
   policy: pull
  script:
   - bundle exec rspec ...
======================

 この設定の良いところは、jobが実行されるスピードを上げ、「キャッシュサーバーのロード」という手間を省くところにあります。
 これは、大量のキャッシュファイルを使うjobが同時進行で動き出すプロジェクトなどで、特に役立つことでしょう。

 ちなみに、jobがキャッシュの復元時に、
その前に使われていたキャッシュコンテンツをまったく無視して、無駄にキャッシュを再構成しているようでしたら、「policy: push」を使うとよいでしょう。
 これには、jobがキャッシュをダウンロードする工程を省略させる効果があります。


 Jobの種類

 .gitlab-ci.ymlファイルには、たくさんのjobを仕掛けることができます。個数は無制限です。
 jobにはまだまだたくさんの種類があります。
 さきほどまで、場面によっては重要なものを選りすぐって紹介してきたのですが、他のものが大事でないわけではありません。
 今度は、jobをもっと1つ1つ丁寧に見ていきましょう。

jobの種類 必須か 説明
script yes ランナーが実行するスクリプトを設定する
image no どのようなDockerイメージを使うかを指定する。 詳しくは Dockerイメージを使うへ。
services no どのようなDockerサービスを使うかを指定する。 詳しくは Dockerイメージを使うへ。
stage no そのjobをどのstageで実行するかを設定する (デフォルト: test)
type no stageにエイリアスを持たせる
variables no ビルドの変数を定義する。jobごとに設定することも可能。
only no jobを適用するgitをどれにするかを設定する
except no jobを適用しないgitをどれにするかを設定する
tags no どのランナーを使うかをタグで指定する
allow_failure no jobが失敗しても、それがコミットに影響しないように設定する
when no jobが実行された後の動作を on_success, on_failure, always あるいはmanualの項目で決定する
dependencies no 特定のjobと依存関係にあるjobを指定する。これを指定すると同時に、jobの順番をある程度定義することもできる。
artifacts no 1つのjobで作り出すもの(job artifacts)を定義する
cache no キャッシュ。ビルドの最中などに何度も使用するファイルを指定するとよい
before_script no それぞれのjobスクリプトの前にしなくてはならないコマンドを指定する
after_script no それぞれのjobスクリプトの後にしなくてはならないコマンドを指定する
environment no 特定のjobが展開する環境を名前で指定する
coverage no jobの許容コード網羅率を指定する
retry no うまくいかなかったjobを自動的に繰り返し、失敗とみなすまでの回数を規定する。

 script

 scriptはランナーが実行するシェルスクリプトを定義するjobです。

======================
job:
  script: "bundle exec rspec"
======================

 このパラメータに、複数のコマンドを指定する時には、次のように設定します。

======================
job:
  script:
   - uname -a
   - bundle exec rspec
======================

 コマンドに入っている文字によっては、「’」や「”」で囲まなくてはならないものもあります。
 たとえば、コロン( :)が必要なコマンドの場合、
 YAML解析プログラムが、正規表現などと混同しないように、コマンドの部分を「’」などで囲んでおく必要があります。(例:『"key: value"』)
 これらの色付けして示した文字が入っているコマンドについては、「’」や「”」で囲むようにしてください。

 :  {  } [ ]  ,  &  *  #  ?  |  -  < > = !  %  @  `


 stage

 stageには複数のjobを各ステージごとに、グループ分けする効果があります。同じステージにあるjobは同時進行で行われるのが特徴です。
 詳しい性質は、このページの上部で説明した通りです。

 onlyとexceptの使い方(基礎編)

 少々長い説明になりますが、onlyとexceptにはそれだけ多様な使い方があります。
 onlyとexceptという2つのパラメータには、jobがどの範囲にわたって適用されるかを指定する部分で、役割が共通しています。

 onlyはjobを適用するブランチやタグを名前で指定するパラメータで、
 exceptはjobを適用しないブランチやタグを名前で指定するパラメータです。

 次のルールを参考に、有効に活用してください。:

  1. onlyexceptはどのjobにも使用可能である。1つのjobにonlyexceptを併用してもよい。その場合、両方の定義に従ってjobが実行される。
  2. onlyexceptは設定に正規表現が使える。
  3. onlyexceptは特定のレポジトリにパスを与える効果もあり、jobを分岐させることができる。その大まかな指定ができるように、いくつものキーワードが用意されている。

キーワード 説明
branches 全てのブランチを指定する
tags 全てのタグを指定する
api パイプラインを 2次パイプラインAPI (triggers APIではなく)に発動させる
external GitLab以外のCIサービスを使用する
pipelines CI_JOB_TOKENで作成されたAPIで、あらゆるプロジェクトのパイプラインを発動させる。
pushes パイプラインをユーザーがgit pushしたときに発動させる。
schedules スケジュールを決定したパイプラインを使う
triggers トリガー・トークンを使ってパイプラインを形成する
web GitLab UIの Run pipeline ボタンから作ったパイプラインを使う。 (これはプロジェクト内の Pipelinesに格納されている。)


 さて、ここで正規表現とキーワードを使った設定例を見てみましょう。

 これは、「issue-」という文字列から始まるファイル(refs)にのみjobを適用し、
 「branches」を除外することで、全てのブランチにそのjobをスキップさせる設定です。

======================
job:
  # ここで正規表現を使ってみる
  only:
   - /^issue-.*$/
 # ここでキーワードを使ってみる
  except:
  - branches
======================


 次の例は、タグの付いたものに、
 トリガー・トークンを使ったAPIか、
 きちんとスケジュールが定められたパイプラインを使って、
 jobを実行させる設定です。

======================
job:
  # この設定はキーワードだけで構成できる
  only:
   - tags
   - triggers
   - schedules
======================


 ひとえに「同じアプリを構成しているレポジトリ」と言えども、異なるバージョンが複数あることは珍しくありません。
 分岐させたバージョンのレポジトリにのみjobを適用し、
 元となったレポジトリには適用させない設定は、次の通り。

======================
job:
  only:
   - branches@gitlab-org/gitlab-ce
  except:
   - master@gitlab-org/gitlab-ce
======================

 この設定では、master以外の「gitlab-org/gitlab-ce」上にある全てのブランチに同じjobが適用されます。

 onlyとexceptの使い方(番外編)

 GitLab 10.0より導入。

 これはまだ、開発アルファ段階にある機能のため、仕様は予告なしに変更される可能性があります。

 このたびGitLabは、「only/except」の設定に新たに2つのパラメータを設けました。

 それは、「refs」と「kubernetes」です。
 「refs」はその下に、従来通りの「only/except」設定キーワードを並べる項目として使われます。
 一方「kubernetes」は、kubernetesを活用する時にのみ使われる項目です。よって、この項目に入れられるキーワードは、「active」のみとなります。

 これらのパラメータを使って、
 kubernetesサービスが起動しているときだけは、
 スケジュールが定まったパイプラインのみを使って、
 masterブランチにだけjobを展開する設定をします。

======================
job:
  only:
   refs:
    - master
    - schedules
   kubernetes: active
======================
  以上でonly/exceptの使い方の説明を終わります。




 jobごとに変数を設ける方法

 さきほども、「変数はjobごとに設けることも可能」であると述べました。
 変数は全体に適用するものがほとんどですが、場面によっては部分的にかけると効果的なことがあります。

 通常、job単位で変数を設定した場合には、全体にかけられた変数と、jobの変数が一緒に実行されることになります。
 全体にかけられた変数を特定のjobで適用したくない場合、jobに次のような空白のカッコを設けてください。

======================
job_name:
  variables: {}
======================

 変数の優先度は「変数説明書」に記載されています。


 tags

 tagsはプロジェクトを動かしている全てのランナーの中から、敢えてどれを使うかを指定する項目です。

 それぞれのランナーにはタグがついています。
 たとえば、「ruby」「postgres」「development」などです。それらを指定することで、

 jobが特定のランナーで作動することになります。

======================
job:
  tags:
   - ruby
   - postgres
======================

 このような設定をすると、「ruby」「postgres」のように、タグで定められたランナーを全て使ってjobを実行していくことになります。


 allow_failure

 allow_failureは、1つのjobの失敗が他のCIに一切影響を与えないことを指定するパラメータです。
 これはどちらかというと、全体に適用するのではなく、部分的に仕掛けるのが良いでしょう。
 jobに失敗があったとしても、コミットの状態に影響しません。

 これにより、パイプラインは見かけの上では緑色の「successful」が表示されていくことになりますが、「CI build passed with warnings(CIは危険なビルド方法を取っています)」というメッセージがマージリクエストやコミット、jobのページに表示されます。

 このオプションは失敗しても大勢に影響しないjobにのみ設定することをお勧めします。

 それから、そのjobが失敗したことを知らせる設定(手動)をしておいた方が良いでしょう。

 次の例では、同じステージが設定されているjob1job2が同時進行で実行されます。
 ただし、job1が失敗しても、滞りなく次のステージが開始されるようになっています。
 job1にだけ「allow_failure: true」と設定しているからです。

======================
job1:
  stage: test
  script:
  - execute_script_that_will_fail
  allow_failure: true

job2:
  stage: test
  script:
  - execute_script_that_will_succeed

job3:
  stage: deploy
  script:
 - deploy_to_staging
======================


 when

 先ほど、jobが失敗しても、それを無視して次の段階に進ませるパラメータは、allow_failureだと説明しました。
 しかし、それでは「jobが失敗したときは、それに対応したjobを始める」ような、「jobのルートづくり」ができていません。

 そこで「when」というパラメータを使います。
 これには前のjobの様子に応じて、次に実行するjobをふるいわける効果があります。

 whenには4つの設定があります。:

  1. on_success - 以前のjobがすべて成功したときに実行する(デフォルト)
  2. on_failure - 以前のjobの中に1つでも失敗があったときに実行する
  3. always - 以前のjobの状態を無視して実行する
  4. manual - このjobにおいてはUIから手動で実行する(GitLab 8.10から追加された項目。詳しくは少し後で説明する)


設定例:

======================
stages:
- build
- cleanup_build
- test
- deploy
- cleanup

build_job:
  stage: build
  script:
  - make build

cleanup_build_job:
  stage: cleanup_build
  script:
  - cleanup build when failed
  when: on_failure

test_job:
  stage: test
  script:
  - make test

deploy_job:
  stage: deploy
  script:
  - make deploy
  when: manual

cleanup_job:
  stage: cleanup
  script:
  - cleanup after jobs
  when: always
======================

 この設定の概要

  1. build_jobが失敗した場合は、cleanup_build_jobが実行される
  2. 以前のjobの成功/失敗に関わらず、パイプラインの一番最後にはcleanup_jobを実行する
  3. deploy_jobについては、GitLabのUIから手動で実行する


 
 
 手動で実行する(Manual actions)とは

 Manual actionsは、GitLab 8.10以降、
 Blocking manual actionsは、GitLab 9.0以降、
 Protected actionsは、GitLab 9.2以降に導入された機能です。

 Manual actionsとは、決して自動的に実行されることのない特殊なjobのことです。
 実行にはユーザーの明らかな指示が必要になります。

 Manual actionsは、パイプライン、ビルド、環境指定、デプロイ・展開の場面を操作できます。
 (環境指定の方法については、環境設定説明書をご覧ください。) 

 先ほどの例では、deploy_jobを手動で実行するよう指定していました。


 Manual actions は、jobの”実行”というより”抑止”の方に、主な役割があるかもしれません。

 特に、Blocking manual actionなどは、stageのパイプラインを一度遮断する役割があります。
 これにより止められたパイプラインは、誰かが手動で「play」ボタンをクリックしない限り、作動しないようになっているのです。

 このモードを使用すると、他のjobが全て成功したとしても、手動のjobを終わらせない限り、ビルドが完了することはありません。

 GitLab CIに本来求められている「自動性」を損なう面があることは確かなので、用途はかなり限定的になるものと思われます。

 しかし、通常「when: manual」にjobの抑止機能がついているわけではありません。
 このパラメータが付けられたjobには「allow_failure:true」が自動で適用されるからです。(デフォルトの設定時)
 あまり必須とはいえない動作が、全体のパイプラインに影響を与えないようにしてあります。

 もしも、手動で実行するjobのために全体のビルド工程を一時停止させたい場合(Blocking manual actions)は、
 任意のjobに「when: manual」と「allow_failure: false」の両方を明記してください。

 Manual actionsには、jobの実行に一段階障壁を設ける役割があります。言い換えれば、パイプラインを適用するブランチを選択したり、必要になったときにだけブランチをマージする猶予が得られるのです。


 environment

 注:

 GitLab 8.9以降に導入。
 ここではCIに入れる項目の1つとして、大まかな解説をいたします。詳しくは、環境設定説明書をご覧ください。


 environmentは、jobが展開する環境を名前で指定するパラメータです。
 これまでに指定したことのない名前を指定すると、その名前のついた環境が新たに作られます。

 もっとも単純な例でいくと、environmentとキーワードは次のように使われます。

======================
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
   name: production
======================

 この設定では、deploy to productionが「production」 という環境で実行されるようになります。

 現在、environmentには5つのキーワードがあります。順番に見ていきましょう。
 

 environment:name

注:

  • GitLab 8.11以降に導入。
  • GitLab 8.11以前は「environment: production」などのようにストリングで定義されていた。現在はnameキーワードの下に配置するように定められている。
  • キーワード「name」の下にはCI用変数(前述)を配置できる。これには定義済み変数、安全変数、.gitlab-ci.yml変数が含まれる。 ただし、パラメータ「script」の配下に設定した変数と同じものを使うことはできない。


 environment nameでは次の文字が使えます。

  • アルファベット
  • 数字
  • スペース
  • -
  • _
  • /
  • $
  • {
  • }

 nameに入る語句には、「qa」「staging」「production」などがよく見受けられますが、これらは利用者のワークフローに応じた名前と上の文字制限を守ったものであれば、何でも構いません。

 キーワードは、「environment」の下に記述するのが正しい使い方です。そして、環境名がその後ろに続きます。
 それさえ守れば、他のキーワードを入れることもできます。
 

======================
deploy to production:
  stage: deploy
  script: git push production HEAD:master
  environment:
   name: production
======================



 environment:url

注:

  • GitLab 8.11以降に導入。
  • GitLab 8.11以前は、GitLab's UIからでないとURLを追加できなかった。現在は.gitlab-ci.ymlで設定するように求められている。
  • キーワード「url」の下にはCI用変数(前述)を配置できる。これには定義済み変数、安全変数、.gitlab-ci.yml変数が含まれる。 ただし、パラメータ「script」の配下に設定した変数と同じものを使うことはできない。

 このオプションは、GitLabの様々な場所にボタンを出現させます。
 URLが定義されているので、きちんと使えます。

 次の例では、jobがきちんと成功したあとに、environments/deploymentsページが作成されます。そこにhttps://prod.example.comというURLにつながった「merge requests」ボタンを設置する設定です。

======================
deploy to production:
 stage: deploy
 script: git push production HEAD:master
 environment:
  name: production
  url: https://prod.example.com
======================

 environment:on_stop

注:

  • GitLab 8.13以降に導入
  • GitLab 8.14から、stop actionが追加。関連しているブランチが消去された時は、ビルドが自動的にストップする機能である。

 これもまた、environmentの下に記述するキーワードです。
 「on_stop」は、jobに通常とは異なる様子があったときに、環境を一時閉鎖する機能です。

 詳しい使い方は、次のenvironment:actionで説明します。

 environment:action
GitLab 8.13以降に導入

 「action」は、環境を閉じるときに呼び出されるjobを定義するキーワードです。
 「on_stop」と連動して使われます。

 使用例:

======================
review_app:
  stage: deploy
  script: make deploy-app
  environment:
   name: review
   on_stop: stop_review_app

stop_review_app:
  stage: deploy
  script: make delete-app
  when: manual
  environment:
   name: review
  action: stop
======================

 この場合、review_app jobdeployのステージでreviewという環境にて実行されます。
 また、stop_review_appについては、on_stopであることがenvironment配下の「action: stop」で定められています。

 review_app job が成功に終わった場合、
次にstop_review_app jobが、パラメータ「when」の内容に従って実行されるはずです。
 今回の場合、whenをmanualに設定していることから、GitLabのインターフェイスから手動で実行することになります。

  stop_review_app jobを設定するには、次のキーワードを定義しなくてはなりません

  • when - 使い方は前述の通り
  • environment:name
  • environment:action
  • stage - 「review_app」と同じステージに設定すること。ブランチが削除された時に、環境を自動停止させるには、同一ステージに設定している必要がある。


 dynamic environments(環境変数を使った設定)

注:

  • GitLab 8.12以降に導入。Gitlab Runner v1.6以上が必要。
  • $CI_ENVIRONMENT_SLUGについてはGitLab 8.15以降に導入
  • 環境キーワード「name」「url」の下にはCI用変数(前述)を配置できる。これには定義済み変数、安全変数、.gitlab-ci.yml変数が含まれる。ただし、先にパラメータ「script」の配下に設定した変数と同じものを使うことはできない。

======================
deploy as review app:
  stage: deploy
  script: make deploy
  environment:
   name: review/$CI_COMMIT_REF_NAME
   url: https://$CI_ENVIRONMENT_SLUG.example.com/
======================

 「deploy as review app」jobは、「review/$CI_COMMIT_REF_NAME」という動的な環境でデプロイを実行します。この「$CI_COMMIT_REF_NAME」というのは、環境変数の一種で、これをランナーが読み取ります。

 その下の「$CI_ENVIRONMENT_SLUG」も変数の一種で、環境名のほか、URLの役割も果たしています。
 もしも、「pow」という名前のブランチにあるアプリケーションにreview(評価)欄をもうけたいときには、ここのURLが「https://review-pow.example.com/」になります。

 もちろん、この操作をする前には、アプリケーションをホストするサーバーの設定が完了している必要があります。

 これは主に、ブランチに動的環境を支度して、アプリケーションを評価(レビュー)してもらう時に使います。
 「 https://gitlab.com/gitlab-examples/review-apps-nginx/」などは、Review Appsを使っているプロジェクトです。ぜひそこのCIファイルをご覧ください。


 artifacts

注:

  • GitLab Runner v0.7.0以降、Windowsを除くプラットフォームに導入。
  • WindowsではGitLab Runner v.1.0.0以降に導入。
  • GitLab 9.2以前では、キャッシュはアプリを生成してから復元される。
  • GitLab 9.2以降は、アプリを生成する前に復元されるよう仕様が変更された。
  • 現在でも一部実行プログラムは対応していない。
  • デフォルトでは成功したjobしか受け付けない。

 artifacts は、関連しているjobが成功したあとに利用していく、ファイルやディレクトリをリスト形式で指定するパラメータです。
 設定はartifactsの下にpathsを設けるだけです。
 このパスには、異なるjobが使うファイルを設定することもできますが、それはこの少し後の『dependencies』の章にて説明します。

 artifactsアーカイブを「binaries」と「.config」内の全ファイルに送る場合

======================
artifacts:
  paths:
  - binaries/
  - .config
======================

 artifactsを全てのGit未追跡ファイルに送る場合

======================
artifacts:
  untracked: true
======================

 artifactsを全てのGit未追跡ファイルと「binaries」ファイルに送る場合

======================
artifacts:
  untracked: true
  paths:
  - binaries/
======================


 artifactの移動を制限したい場合は、キーワード「dependencies:」に空カッコを設けてください。

======================
job:
  stage: build
  script: make build
  dependencies: []
======================

 一時的にビルドにいちいちサーバーのストレージを裂くのがもったいない場合は、タグが付いたリリースにのみ、artifactsを作成させるとよいでしょう。

 tagsがついたartifactsのみを作成し、default-jobではartifactsを作り出さない設定:
 

======================
default-job:
  script:
   - mvn test -U
  except:
   - tags

release-job:
  script:
   - mvn package -U
  artifacts:
   paths:
   - target/*.war
  only:
   - tags
======================

 この設定で、artifactsはjobが正しく成功してからGitLabに送りだされ、GitLab UIからダウンロードできるようになります。

 以上がartifactsの基本的な使い方です。
 次は、artifacts用キーワードの使い方を説明します。
 3種類あります。

 artifacts:name

GitLab 8.6以降に導入。Gitlab Runner v1.1.0以上が必要。

 「name」はartifactsアーカイブの名前を定義するキーワードです。
 ここでは、GitLabからアーカイブをダウンロードした時のことを考えて、何か分かりやすい名前を付けておくとよいでしょう。

 artifacts:nameには、すべての定義済み変数を代入することができます。

 デフォルトでの名前は「artifacts」です。
 この名前でダウンロードできるアーカイブは「artifacts.zip」になるはずです。

 現在のjobの名前をアーカイブにつける場合(定義済み変数)

======================
job:
  artifacts:
   name: "$CI_JOB_NAME"
======================

 現在のブランチか、Git未追跡ファイルでもタグのついているものにしかアーカイブを設けない場合

======================
job:
  artifacts:
   name: "$CI_COMMIT_REF_NAME"
   untracked: true
======================

 現在のブランチか、Git未追跡ファイルでもタグのついているものにしかアーカイブを設けないうえに、
 アーカイブに現在のjobの名前をつける場合

======================
job:
  artifacts:
   name: "${CI_JOB_NAME}_${CI_COMMIT_REF_NAME}"
   untracked: true
======================

 現在のステージとブランチとをアーカイブの名前にする場合

======================
job:
  artifacts:
   name: "${CI_JOB_STAGE}_${CI_COMMIT_REF_NAME}"
   untracked: true
======================

 Windows Batchを使ってシェルスクリプトを動かしている場合は、 「$」を「%」に置き換えなくてはならない。

======================
job:
  artifacts:
   name: "%CI_JOB_STAGE%_%CI_COMMIT_REF_NAME%"
   untracked: true
======================

 Windows PowerShellでシェルスクリプトを動かしている場合は、「$」を「$env:」に置き換えなくてはならない。

======================
job:
  artifacts:
   name: "$env:CI_JOB_STAGE_$env:CI_COMMIT_REF_NAME"
   untracked: true
======================

 artifacts:when

GitLab 8.9以降に導入。Gitlab Runner v1.3.0以上が必要。

 artifacts:whenは、jobの成功/失敗などの場合に応じて、artifactsをアップロードするかどうかを決められるキーワードです。

 artifacts:whenには3つの設定があります:

  1. on_success - jobが成功したときにのみartifactsをアップロードする(デフォルト)
  2. on_failure - jobが失敗したときにのみartifactsをアップロードする
  3. always - jobの成功/失敗に関わらずartifactsをアップロードする

 jobが失敗したときにのみartifactsアーカイブをアップロードする場合

======================
job:
  artifacts:
   when: on_failure
======================



 artifacts:expire_in

GitLab 8.9以降に導入。Gitlab Runner v1.3.0以上が必要。

 atifacts:expire_inは、一定期間をすぎたartifactsのアップロードを取りやめさせるキーワードです。
 デフォルトでは、アーカイブは無期限に公開され続けます。
 そこに任意の期間を設定し、GitLabにアップロードしてから収容していた時間を計測してやめさせる機能です。

 また、jobページにある「Keep」ボタンを押せば、一度期限を設定してしまったjobでも、あとから公開期限を撤廃することが可能です。すると、jobは無期限公開になります。

 期限を過ぎたアーカイブにつきましては、一時間ごとに消去される仕組み(デフォルト。cron jobを参照)でして、それ以降は一切のアクセスができなくなります。

 expire_inに設定する時間ですが、次のような表記が可能です。

  • '3 mins 4 sec'
  • '2 hrs 20 min'
  • '2h20min'
  • '6 mos 1 day'
  • '47 yrs 6 mos and 4d'
  • '3 weeks and 2 days'
 上から、「3分4秒」「2時間20分」「2時間20分」「6か月と1日」「47年6か月と4日」「3週間と2日」といった具合です。


 設定例:
 artifactsの公開期限を1週間にする

======================
job:
  artifacts:
   expire_in: 1 week
======================


 dependencies

 GitLab 8.6以降に導入。Gitlab Runner v1.1.1以上が必要。

 このパラメータは、artifactsに異なるjob動詞を結んだパスを与えます。
 従って、パラメータ「artifacts」と併用されることになります。

 artifactsが作成されるのは、デフォルトでは全てのstagesが終了してからとなっています。

 この機能を使うには、jobに関連する依存関係を洗い出す必要があります。その前の段階に行われたすべてのjobとパスのリストを調べてください。
 それらがダウンロードされるartifactsのもとになります。

 dependenciesは目的のjobの前に、必ずや実行しなくてはならないjobを定義しておくという割と単純なパラメータです。
 このパラメータに定義しておいたjobがエラーを起こすと、そのパラメータをつけているjobもエラーを起こします。
 このパラメータを空白にしておくと、一切のartifactsのダウンロードを省略します。
 なお、パラメータにまったく関係のないjobをを登録しておいて、そのjobが失敗した、
 もしくは登録した手動jobが、まだ実行されていない場合は、エラーが起こったとはみなされません。

 次の例では、「build:osx」と「build:linux」という2つのjobが定義されています。どちらもartifactsが設定されているものです。
 「test:osx」が実行されるときには、「build:osx」からartifactsがダウンロードされ、ビルドに必要なデータが抜き出されます。

 同じことが「test:linux」と「build:linux」にもいえます。

 最後の「deploy」jobにおいては、その前に行われた全てのjobからartifactsを受け取ったのちに実行されます。

======================
build:osx:
  stage: build
  script: make build:osx
  artifacts:
   paths:
   - binaries/

build:linux:
  stage:
build
  script: make build:linux
  artifacts:
   paths:
   - binaries/

test:osx:
  stage: test
  script: make test:osx
  dependencies:
  - build:osx

test:linux:
  stage: test
  script: make test:linux
  dependencies:
  - build:linux

deploy:
  stage: deploy
  script: make deploy
======================



 before_script と after_script

 「before_script」と「after_script」は、上の表にもある通り、使い方がほとんど一致するため、一括で説明する。

======================
before_script:
- 全体的に実行しておきたいスクリプトを入れる

job:
  before_script:
  - ここには全体にかけられたbefore_scriptの代わりに実行したいスクリプトを入れる
  script:
  - ここにコマンドを入れる
  after_script:
  - すぐ上のコマンドの後に実行するスクリプトを入れる
======================


 coverage

注:

 coverageは、jobが出力できた割合をもとに、どのくらいのコード網羅率になれば認可を出すかを指定するパラメータです。

 この項目に入れられるのは、正規表現のみです。ご注意ください。
 なお、「/」を表現に用いることが可能です。システムに応じた正規表現をご利用ください。
 ここでは正規表現を忠実に表すことが肝心です。エスケープ特殊文字( escape special characters)も使ってください。

======================
job1:
  script: rspec
  coverage: '/Code coverage: \d+\.\d+/'
======================

 retry

注:

 retryはうまくいかなかったjobを自動的に繰り返し、失敗とみなすまでの回数を規定するパラメータです。

 retryを「2」とセットしていても、1回目のリトライでjobが成功した場合はそれ以上やり直しません。
 同じように、retryで規定された回数以下でjobのやり直しが終わってしまう場合がありますが、これは正常な動作です。

  ここに入れる数字は、0から2までの正の整数にしてください。
 「2」と設定した場合、最大2回のリトライが実施され、結果的に最大3回jobが実行される計算です。

======================
test:
 script: rspec
 retry: 2
======================

 Git Strategy

  • GitLab 8.9に試験導入。
  • 将来のリリースで変更あるいは消去が検討されている機能。
  • GitLab Runner v1.7以降では必要とされないパラメータ。

 GIT_STRATEGYは、比較的新しくアプリケーションコードに使われるようになったパラメータです。グローバル変数の設定や、jobごとに変数を設ける項目として機能します。
 この項目をこれといって指定しなかった場合は、プロジェクトのデフォルト設定が適用されます。

 キーワードは「clone」「fetch」「none」の3種類です。

 この中では「clone」がもっとも動きの遅いオプションです。
 これは、各jobから1つ1つレポジトリのクローンを生成し、プロジェクトのワークスペースをいつも最新のものに改めます。

======================
variables:
  GIT_STRATEGY: clone
======================

 「fetch」はプロジェクトのワークスペースを再利用するスピードが最も速いオプションです。
 最新バージョンが見当たらなかった場合は、以前のバージョンをクローンします。
 「git clean」は最後のjobで追加された変更を無かったことするために、「git fetch」は最後のjobが作り出したコミットを埋め合わせるために使われます。

======================
variables:
  GIT_STRATEGY: fetch
======================

 プロジェクトのワークスペースをそこまで何度も使わない場合は、Gitのチェック回数(GitLab ランナーによるプレ・クローンスクリプトなども含む)を削減したらよいでしょう。そこで使われるのが「none」です。
 特にartifactsを管理する時(例:deploy)には、このモードがもっとも使い勝手の良いオプションであると思われます。

 Gitレポジトリのデータは、あまりにも古いものを持ってこずに、なるべく新しい方のものを採用します。
 よって、プロジェクトのワークスペースに持ってこられるファイルは「cache」か「artifacts」内にあったものになるでしょう。
======================
variables:
  GIT_STRATEGY: none
======================

 Git Checkout

GitLab Runner 9.3以降に導入。

 
 「GIT_CHECKOUT」は、「GIT_STRATEGY」が「clone」あるいは「fetch」に指定され、gitをチェックする頻度が極端に定められている場合に使われるパラメータです。
 
 グローバル変数や、jobごとに変数をあたえる設定が可能なところは、「GIT_STRATEGY」に共通します。

 これといった設定をしなかった場合は、デフォルトの設定「ture」が使われます。

 それではこのパラメータに「false」が設定された場合、ランナーがどのような動作をとるか:

fetch」が設定されていた場合 - レポジトリをアップデートし、現在のバージョンの作業コピーを中止する。
clone」が設定されていた場合 - レポジトリをクローンし、デフォルトのブランチの作業コピーを中止する。
 
 ただし、これらのキーワードを設定していたとしても、GIT_CHECKOUTが「true」に設定されていた場合、ランナーはCIパイプライン側が変更したバージョンに従って作業コピーを作成します。

======================
variables:
  GIT_STRATEGY: clone
  GIT_CHECKOUT: false
script:
  - git checkout master
  - git merge $CI_BUILD_REF_NAME
======================



 Git Submodule Strategy

 GitLab Runner v1.10以上が必要。

 アプリをビルドする前にランナーがコードを確認する工程があるのですが、「GIT_SUBMODULE_STRATEGY」は、その時にGitサブモジュールをどのように使うかを指定するパラメータです。
 グローバル変数や、jobごとに変数をあたえる設定が可能なところは、「GIT_STRATEGY」に共通します。

  キーワードは「none」「normal」「recursive」の3種類です。

 「none」はコードを確認する工程にGitサブモジュールを一切使用しないという設定です。
 デフォルトではこれが設定されており、GitLabランナーはこの機能がなかったころ(v1.10以前)と何ら変わりのない振る舞いをします。

 「normal」はトップレベル・Gitサブモジュールだけをコード確認工程に使用する設定です。
  このキーワードには以下のコマンドが設定されています:

======================
git submodule sync
git submodule update --init
======================
     

 「recursive」は、全てのサブモジュール(サブモジュールが使用するサブモジュールもある)を使用する設定です。
  このキーワードには以下のコマンドが設定されています:

======================
git submodule sync --recursive
git submodule update --init --recursive
======================
         

 ※この機能を正常に使うには、あらかじめ「.gitmodules」というファイルにサブモジュールの設定をしておかなくてはなりません。
 特に、これらの要点を押さえてください。

  • 外部のサーバーのレポジトリからサブモジュールを利用する場合は、publicly-accessible(外部アクセス許可)レポジトリのHTTP(S) URLを定義すること
  • 同じGitLabサーバーにあるレポジトリを指定する場合は、それに対応したパスを設けること。この方法については、Git submodules説明書を参照。


 Job stages attempts

 初代GitLab から導入(Introduced in GitLab)。Gitlab Runner v1.9以上が必要。

 各jobには、その役割を効率よく実行するために、できる限り完成させようとする大まかな指令があります。
 以下のパラメータを使うと、それに関係する個数を変更することができます。

キーワード 説明
GET_SOURCES_ATTEMPTS jobを実行する時に参照するソースの個数を設定する
ARTIFACT_DOWNLOAD_ATTEMPTS jobを実行する時にダウンロードするartifactsアーカイブの個数を設定する
RESTORE_CACHE_ATTEMPTS jobを実行する時に復元するキャッシュの個数を設定する

 デフォルトでは、attemptの個数はそれぞれ1つづつ与えられています。

 設定例:

======================
variables:
  GET_SOURCES_ATTEMPTS: 3
======================

 みなさんもうお判りでしょうが、これらのキーワードは全て変数です。
 もちろん、他の変数と同様にjob全体に適用させることもできます。



 Shallow cloning(深追いさせないGitクローン)

GitLab 8.9に試験導入。将来のリリースで変更あるいは消去が検討されている機能。

 ビルドの際にコードを参照するときにしても、Gitをクローンするにしても、そんなに古いバイナリやコミットにまで追求する必要はないはずなのです。

 「GIT_DEPTH」はGitをどこまで追求させるかを指定するパラメータです。
 この項目で、「git fetch」と「git clone」の両方の回数を決定します。

注:ここの数値を「1」にした場合、複数のjobをこなしたり、失敗したjobをリトライすることができなくなります。

 同様に、この数値を小さくし過ぎることで、古いコミットがあまりにも試せない状況を作り出してしまうことがあります。
 スピードを優先させたつもりで、かえってjob全体が停滞してしまう可能性が高いので、なるべく余裕を持った数値を設定しましょう。
 jobのログに「unresolved reference」と表示されることがありますが、それは数値が低すぎる時の目安になります。

 ブランチ名を指定した場合など、refを基準にしたクローンやコード参照をしているときには、ランナーが特定のSHAコミットをクローンすることはできません。

 GIT_DEPTHがGit履歴のみを対象にセットしているときには、git describeに依存しているJobが正しく動作しない場合があります。

 新しい順に3つまでのコミットしか、「fetch」「clone」させない場合

======================
variables:
  GIT_DEPTH: "3"
======================


 jobを否定するキー

GitLab 8.6以降に導入。Gitlab Runner v1.1.1以上が必要。

 もしも一時的に’差し止めたい’jobがあるとするならば、よくある方法としてjobをコメントアウト(コードをコメント記号で囲み,コンパイル対象から外すこと)が考えられますが…

======================
#hidden_job:
#  script:
#   - run test
======================

 それよりかは、job名の先頭にドットマーク(.)を付けた方が、簡単ですよ。
 こういう表記にしてください。

======================
.hidden_job:
  script:
   - run test
======================

 無視させたいjobを設定する方法には、YAMLの機能を使ったものもありますので、そちらも参考にしてください。すぐ下からその解説です。


 YAMLのちょっと変わった機能

 CIが便利だからって、あれこれ設定していると、いつの間にか.gitlab-ci.ymlがかなり複雑になります。
 しかし、YAMLの特殊機能である、アンカー(&)、エイリアス( *)、マップ上書き( <<)を使うと、一気に解決できることがあります。

 YAMLの特殊機能については、こちらのページに詳しく載っています。

 Anchors

GitLab 8.6以降に導入。Gitlab Runner v1.1.1以上が必要。

 YAML特殊機能の中でも、特に使う場面が多いのが「anchors」です。これを使うと、.gitlab-ci.ymlのコンテンツを簡単に複製できるのです。

 アンカーは、コンテンツの複製と継承とに使うことができます。
 それではこれから、YAMLの秘密キーがjobのテンプレートの役割を担っている事例を紹介しましょう。

 以下の例ではアンカー(&)とマップ上書き(<<)を使っています。

 「.job_template」というパラメータを、「test1」と「test2」のjobに引き継がせます。2つのjobはそれぞれ別々のscriptが定義されています。

======================
.job_template: &job_definition # ここに「&」記号で、'job_definition'という要素にジャンプするアンカーを設けました。
  image: ruby:2.1
  services:
   - postgres
   - redis

test1:
  <<: *job_definition # さらに「*」記号で'job_definition' のエイリアスを設け、ここをアンカーの転送先としました。
  script:
   - test1 project
test2:
  <<: *job_definition # さらにここにも「*」記号で'job_definition' のエイリアスを設け、アンカーの転送先としました。
  script:
   - test2 project
======================

&」にはアンカーの名前(job_definition)を、
<<」には、(ちょうどHTMLのハッシュのような役割があり、)
その後に具体名(job_definition)を入れると、それがどこのアンカーを担当しているかが明記されます。

 しかし、上に示しましたのは、YAMLの使い方をわかりやすくするために、色々と細かい所を省略した図です。
 実際は以下のような設定ファイルをもとに、さらにYAML特殊機能を追加したものとイメージしていただければ、よろしいかと思われます。

======================
.job_template:
  image: ruby:2.1
  services:
   - postgres
   - redis

test1:
  image: ruby:2.1
  services:
   - postgres
   - redis
  script:
   - test1 project

test2:
  image: ruby:2.1
  services:
   - postgres
   - redis
  script:
   - test2 project
======================

 さらに別の事例を見てまいりましょう。
 大まかにいえば、1つのjobを他の2つのjobに引き継がせるところは上と同じです。

 基本は「.job_template」jobで指定されたscript(test project)をその下の「test:postgres」「test:mysql」jobに引き継がせる設定です。
 
 そこにさらに2つのjob「.postgres_services」「.mysql_services」を追加しています。
 この内容をそれぞれ「test:postgres」「test:mysql」以下に指定されているパラメータ「services」でも使用するという設定です。

======================
.job_template: &job_definition # ①
  script:
   - test project

.postgres_services: # ②
  services: &postgres_definition
   - postgres
   - ruby

.mysql_services: # ③
  services: &mysql_definition
   - mysql
   - ruby

test:postgres:
  <<: *job_definition  # ①から引き継ぎ
  services: *postgres_definition # この内容は②と共有

test:mysql:
  <<: *job_definition # ①から引き継ぎ
  services: *mysql_definition  # この内容は③と共有
======================

 さて、YAMLキーを使わなかった設定が、こちらです。
 なんだか、設定内容に繰り返しが多いですね。

======================
.job_template:
  script:
   - test project

.postgres_services: 
  services:
   - postgres
   - ruby

.mysql_services: 
  services:
   - mysql
   - ruby

test:postgres:
  script:
   - test project
  services:
   - postgres
   - ruby

test:mysql:
  script:
   - test project
  services:
   - mysql
   -
ruby
======================

 Triggers

 Triggersは特定のブランチ、タグ、コミットをAPIを呼び出してリビルドさせる使い道もあります。
 詳しくは、triggers説明書をご覧ください


 pages

 pagesは、GitLabで静的サイトを公開するときに使います。
 少し変わったシンタックスで、次の2つの条件を守って設定する必要があります。

  1. 静的コンテンツはすべて「public/」ディレクトリに入れること
  2. artifacts」というキーワードの下に、「public/」へのパスを設けること

 それから、.publicのコピーを一時的に抑制する設定をすると、「public/」ディレクトリをコピーし続ける無限ループを防止できます。
======================
pages:
  stage: deploy
  script:
  - mkdir .public
  - cp -r * .public
  - mv .public public
  artifacts:
   paths:
   - public
  only:
  - master
======================
 詳しくはGitLab Pages説明書をご覧ください。


  .gitlab-ci.ymlで使えるデバックツール

 GitLab CIでは、「Lint」という埋め込み型デバックツールを使うことができます。
 gitlab内の「/ci/lint」以下にリンクが張られます。

 キーワードを使ったときにエラーが出た

 特定のキーワードを使用したときに、エラーが表示されることがあります。
 「script」の章でも解説しましたが、YAML解析プログラムに誤解されやすい文字が入ったコマンドを「'」「"」で囲みましたか?
 それでもだめなら、スクリプトを少し違う形式で書いてみるなりしてください。(例:/bin/true

 jobをスキップする

 コミットメッセージに[ci skip]あるいは[skip ci]を入れておくと、そのコミットでのjobの実行は省略されます。

 各言語にあったCIファイルを見たい

 『GitLab CI 設定サンプル集 』というページには、それぞれのプログラミング言語に応じたCI設定が掲載されています。ぜひ、参考にしてください。

原文:https://docs.gitlab.com/ee/ci/yaml/README.html
原文ページプロジェクト並びにドキュメントファイルは、MIT Licenseのもと公開されています。(URL:https://gitlab.com/gitlab-com/gitlab-docs/blob/master/LICENSE) この記事の文章は、訳者の判断によりCreative Commons BY (version 3.0) を適用するものとします。
新着文書(Hnoss)

Hugo Static Site Generator with CI Deployment using GitLab | Leow Kah Man - Tech Blog
 週末にかけて、GitHubに構えていた私のブログをGitLabに移転しました。GitLabだとCIビルドが自動的にできるところが便利です。  僕はGitLabのレポ...
Using Docker images
GitLab Documentation > GitLab Continuous Integration (GitLab CI) > Docker integration >Dockerイメージを使う  GitLab CIは、Gi...
GitLab CI/CD Variables
GitLab Documentation > GitLab Continuous Integration (GitLab CI) >GitLab CI/CDで使えるAPI変数  GitLab ランナーは、CIから送られてきたj...

新着文書

Revisit to resist: Histories of the movement to end gender-based violence
抵抗のための再検討:ジェンダーに基づく暴力を終わらせるための活動の歴史 2017年11月8日 記憶は抵抗である。あなたの話が沈黙させられ挑まれたな...
What do women’s rights have to do with the SDGs and the internet?
女性の権利はSDGsとインターネットにどのような関係があるか? 2017年8月2日、スリランカ 女性は均質な集団ではなく、科学技術へのアクセスもまた、...
Sexual rights and the internet: Third EROTICS global survey now launched!
性的権利とインターネット:第3回EROTICS国際調査、現在開始! 2017年7月19日 EROTICS国際調査が戻ってきた! もしあなたが、インターネットを自ら...

新着Wikipedia翻訳

Air gap (networking)
エアギャップ(ネットワーク関係) エアギャップ(air gap:空隙)またはair wall(空気壁)、エア・ギャッピング[1]とは、ネットワーク・セキュリ...
HTTP Public Key Pinning
HTTP公開鍵ピニング HTTP公開鍵ピニング(HPKP: HTTP Public Key Pinning)[1]とは、HTTPヘッダによって実現されるセキュリティの仕組みであり、HT...
Double Ratchet Algorithm
ダブル・ラチェット・アルゴリズム 「ダブル・ラチェット」はこの項目へ転送されています。工具については レンチ を参照下さい。 暗号技術におい...

更新履歴

※文書量によっては処理に数十秒かかる場合があります
バージョン 比較対象 更新日時 更新者
1(最新) 2017-11-17 23:50:25 Hnoss
2 2017-11-17 23:38:45 Hnoss
3 2017-11-17 23:31:30 Hnoss
4 2017-11-17 23:27:02 Hnoss
5 2017-11-14 21:34:26 Hnoss
6 2017-11-14 21:33:53 Hnoss
7 2017-11-13 21:23:09 Hnoss
8 2017-11-13 21:19:00 Hnoss
9 2017-11-13 21:13:33 Hnoss
10 2017-11-13 21:11:02 Hnoss

    
ブックマーク登録

タグを「;(半角セミコロン)」区切りで入力して下さい(例)tag1;tag2;tag3
10タグまで登録可能。各タグ30文字まで

履歴
状態 作業中 作業予定あり 作業予定なし 作業完了
テーマ 社会 政治 法律 経済 文化 芸能 科学技術 IT 健康/医療 スポーツ メディア 植物 動物 菌類 地方 国際
地域 日本 東アジア アフリカ 南アジア 東南アジア 西アジア/中東 太平洋 北米 中南米 欧州
ジャンル ニュース 解説記事 論文 日記 百科事典

コメントを入力して下さい
0 / 250
    
ブックマーク登録

ブックマークに登録しました。


言語選択

    
ファイルプロパティ

使用許諾条件
ファイル情報
あなただけがこのファイルを閲覧・編集できます。
みんながこのファイルを閲覧できますが、
編集ができるのはあなただけです。
あなたに加えて、指定された人やグループが
このファイルを自由に閲覧・編集できます。
公開設定
編集設定
グループ:0組 翻訳者:0人
    
アクセス属性
この文書は「非公開」設定になっています。
一般公開する場合は、編集ページの書誌情報で「公開」設定に変更して下さい。
翻訳者選択

※メニュー「翻訳者管理」で翻訳者、グループを追加することができます。


    
ノート

非公開ノート
0 / 2000 ※「公開・編集」権限を持つ翻訳者のみに公開されます。
公開ノート
0 / 2000 ※文書を「公開」にした場合、一般に公開されます。

言語選択

 →