.gitlab-ci.ymlの動作原理

10月 5, 2022 GitLab, 技術文書

`.gitlab-ci.yml` ファイルとは

.gitlab-ci.yml ファイルはパイプラインの構造と順序を定義し、以下のことを決めます。

Gitlab Runnerを使って実行する内容。
特定の状況において、どのような判断をするか。例えば、処理が成功した場合と失敗した場合。

stages、ジョブの実行順序

■ジョブは .gitlab-ci.yml ファイルの最も基本的な要素です。

ジョブの定義及び特徴：

ジョブとは、何をするかを定義するものです。例えば、コードをコンパイルしたり、テストしたりするジョブがあげられます。

どのような条件で実行されるべきかを示す制約とともに定義されます。
任意の名前を持つトップレベル要素で、少なくとも script句を含んでいます。
定義できる数に制限はありません。
ジョブはRunnerによって実行されます。同じステージ内の複数のジョブは、同時に動作可能なRunnerがあれば並列に実行されます。
ステージ内のすべてのジョブが成功すれば、パイプラインは次のステージに進みます。
あるステージのジョブがどこかで失敗すると、一般的に次のステージは実行されず、パイプラインはそこで終了します。

使用例：

job1:
  script: "execute-job1"

job2:
  script: "execute-job2"

■stagesは、ジョブを含有するステージを定義するために使用され、パイプラインに対してグローバルに定義されます。

stageの仕様により、柔軟な多段パイプラインを構築できます。 stagesの要素の順序が、ジョブの実行順序を定義します。
同じステージのジョブは並列に実行されます。（同時に動作可能なRunnerがあれば並列に実行されます。）
次のステージのジョブは、前のステージのジョブが正常に終了した後に実行されます。

使用例：

stages:
  - build
  - test
  - deploy

はじめに、buildのジョブがすべて並列に実行されます。
buildのすべてのジョブが成功した場合、testのジョブが並列に実行されます。
testのすべてのジョブが成功した場合、deployのジョブが並列に実行されます。
deployのすべてのジョブが成功した場合、コミットは成功とマークされます。
前のジョブのいずれかが失敗した場合、コミットは失敗とマークされ、それ以降のステージのジョブは実行されません。
※【レアケース】：gitlab-ci.yml に stages が定義されていない場合、デフォルトでは build、test、deploy がジョブのステージとして使用されます。
※【レアケース】：ジョブでstageを指定していない場合、ジョブにはtestステージが割り当てられます。

needs:キーワードについて

needs:キーワードにより、.gitlab-ci.ymlで有効非巡回グラフ（DAG）を実装でき、ジョブの実行順を柔軟にできます。

これにより、いくつかのジョブを他のジョブを待たずに実行することができ、ステージの順番を無視して複数のステージを同時に実行することができます。

使用例：

linux:build:
  stage: build

mac:build:
  stage: build

lint:
  stage: test
  needs: []

linux:rspec:
  stage: test
  needs: ["linux:build"]

linux:rubocop:
  stage: test
  needs: ["linux:build"]

mac:rspec:
  stage: test
  needs: ["mac:build"]

mac:rubocop:
  stage: test
  needs: ["mac:build"]

production:
  stage: deploy

この例では、4つの実行パスを作成します。

Linter: lintジョブはneedsがない(needs: [])ので、buildステージが完了するのを待たずにすぐに実行されます。
Linuxパス: linux:rspecとlinux:rubocopジョブは、linux:buildジョブが終了するとすぐに実行され、mac:buildが終了するのを待たずに実行されます。
macOS パス: mac:rspec と mac:rubocop ジョブは mac:build ジョブが終了するとすぐに実行され、linux:build が終了するのを待たずに実行されます。
production ジョブは前のジョブが終了するとすぐに実行されます。この場合は、linux:build、linux:rspec、linux:rubocop、mac:build、mac:rspec、mac:rubocopが前のジョブに該当します。

Git clean flags変数について

GIT_CLEAN_FLAGS変数は、ソースをチェックアウトした後のgit cleanのデフォルトの振る舞いを制御するために使用します。グローバルに、あるいはジョブごとに設定することができます。variablesセクションで設定できます。

GIT_CLEAN_FLAGSは、このコマンドで指定できるすべてのオプションを受け付けます。 git cleanコマンドのすべてのオプションを受け入れます。

GIT_CHECKOUT: “false “を指定すると、git cleanは無効になります。
GIT_CLEAN_FLAGSがある場合。
- 指定しない場合、git cleanflags のデフォルトは-ffdxとなります。
- noneを指定すると、git cleanは実行されません。

使用例：

以下の「.gitlab-ci.yml」サンプルは[build-job]ジョブにて[mkdir projects]はprojectsのdirectoryを作成しましたが、次の[test-job]を実行される前に、自動的にclean up（Removing projects/）の処理を実行されますので、[build-job]ジョブで作成されたprojectsのdirectoryを削除されます。[test-job]ジョブに環境変数[GIT_CLEAN_FLAGS: -ffdx -e projects/]を指定すれば、[build-job]ジョブにて作成されたproject directory と file が削除しないように実現できます。

.gitlab-ci.yml

stages:											
    - build											
    - test											
											
build-job:											
  stage: build											
  script:											
    - pwd											
    - ls											
    - mkdir projects											
    - cd projects											
    - echo $CI_JOB_NAME											
											
test-job:											
  stage: test											
  variables:											
    GIT_CLEAN_FLAGS: -ffdx -e projects/ 											
  script:											
    - pwd											
    - ls											
    - echo $CI_JOB_NAME

Running with gitlab-runner 15.3.0 (bbcb5aba)
- on dnp-group-runner JQw2qXrk
Resolving secrets
- シークレット認証
Preparing the “shell” executor
- Excutor準備
Preparing environment
- 環境準備
Getting source from Git repository
- 共通環境変数とjobで宣言した環境変数を設定(export)
  - 例：GIT_CLEAN_FLAGS=-ffdx -e xxxx/
- Gitリポジトリから対象ブランチのソースをプロジェクトフォルダにダウンロード（git fetch + git checkout)
- プロジェクトフォルダをクリーンアップ(git clean -ffdx)
  - 注意：追跡対象外ファイルとフォルダを削除
Executing “step_script” stage of the job script
- プロジェクトフォルダでscriptsに指定されたコマンドを順番に実行
Cleaning up project directory and file based variables
- tempファイル削除
Job succeeded

includeパラメータについて

includeパラメータを使用すると、このジョブが外部YAMLファイルを含むことを許可し、外部のYAMLファイルを含有することができます。これにより、CI/CDの設定を複数のファイルに分解し、長い設定ファイルの可読性を高めることができます。また、テンプレートファイルを中央のリポジトリに保存し、プロジェクトにその設定ファイルを含めることも可能です。これは、すべてのプロジェクトのグローバルデフォルト変数など、設定の重複を避けるのに役立ちます。

includeは外部のYAMLファイルが拡張子.ymlか.yamlを持っている必要があり、そうでなければ外部ファイルはインクルードされません。

includeは以下のインクルード方法をサポートしています。

方法	説明
local	ローカルのプロジェクトリポジトリからファイルをインクルードします。
file	別のプロジェクトリポジトリからのファイルをインクルードします。
remote	リモートURLからのファイルをインクルードします。公開されている必要があります。
template	GitLabが提供しているテンプレートをインクルードします。

① include:local

include:local は .gitlab-ci.ymlと同じリポジトリのファイルをインクルードします。ルートディレクトリ(/)からの相対的なフルパスを使用して参照されます。

設定ファイルと同じブランチにある、すでにGitで管理されているファイルしか使えません。つまり、include:localを使う場合は、.gitlab-ci.ymlとローカルファイルの両方が同じブランチにあることを確認してください。

使用例：

include:
  - local: '/templates/.gitlab-ci-template.yml'

② include:file

同じ GitLab インスタンスの下にある別のプライベートプロジェクトのファイルをインクルードするには、include:file を使用します。このファイルは、ルートディレクトリ(/)からの相対的なフルパスを使って参照されます。refも指定できますが、デフォルトはプロジェクトのHEADです。

使用例：

include:
  - project: 'my-group/my-project'
    ref: master
    file: '/templates/.gitlab-ci-template.yml'

③ include:remote

include:remote を使用すると、別の場所からのファイルをインクルードすることができます。 HTTP/HTTPS を使用して、完全な URL を使用して参照されます。リモートURLの認証スキーマはサポートされていないため、リモートファイルは単純なGETリクエストで公開されなければなりません。

使用例：

include:
  - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'

publicアクセスできない別のproject (GitLab.com のprivate projectsなど) のファイルにアクセスしたい場合は、URL の基本的な認証スキーマも include 値の変数もまだサポートされていないため、本来はアクセスできませんが、しかし、下記の裏技でinclude可能となります。

使用例：

include: 
  - remote: 'https://gitlab.com/api/v4/projects/123456/repository/files/templates%2F.ci-deploy-lib.yml/raw?ref=master&private_token=ABCDEFG&fmt=.yml'

gitlab.com/api/v4/projects/xxxxxx/repository/files ：GitLab API (Repository Files)
123456 ： project ID
templates：file_path
%2F：”/”のURLエンコード
.ci-deploy-lib.yml：include対象 .ymlファイル
master：ブランチの名前
ABCDEFG ： projectにアクセス権限ありのToken

認証スキーマ（Token）は環境変数にすることができないのは残念な点なのですが、上記ようなURLに直接にTokenを埋めるより、publicアクセス権限ないprivate projectのYAMLファイルをincludeすることができます。

④ include:template

include:templateを使うと、GitLabに同梱されている.gitlab-ci.ymlのテンプレートをインクルードすることができます。複数ファイルのinclude:template: もインクルードすることができます。

使用例：

include:
  - template: Android-Fastlane.gitlab-ci.yml
  - template: Auto-DevOps.gitlab-ci.yml

.gitlab-ci.ymlの動作原理

目次

.gitlab-ci.yml ファイルとは

stages、ジョブの実行順序

needs:キーワードについて

Git clean flags変数について

includeパラメータについて

GitLabでpythonのテストレポートとカバレッジの可視化

GitLabでJavaのテストレポートとカバレッジの可視化

shellでのGitLab API呼び出し

Runnerの動作原理

`.gitlab-ci.yml` ファイルとは