他のファイルのCI/CD設定を使用する

includeを使用して、外部のYAMLファイルをCI/CDジョブにインクルードできます。

単一の設定ファイルをインクルードする

単一の設定ファイルをインクルードするには、次のいずれかの構文オプションで、includeを単独で使用します:

• 同じ行に記述する場合:

  include: 'my-config.yml'

• 配列内の単一の項目として記述する場合:

  include:
    - 'my-config.yml'

ファイルがローカルファイルの場合、include:localと同じ動作になります。ファイルがリモートファイルの場合、include:remoteと同じ動作になります。

設定ファイルの配列をインクルードする

設定ファイルの配列をインクルードできます:

• includeタイプを指定しない場合、必要に応じて、各配列項目はデフォルトでinclude:localまたはinclude:remoteとして扱われます:

  include:
    - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'
    - 'templates/.after-script-template.yml'

• 単一の項目の配列を定義できます:

  include:
    - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'

• 配列を定義して、複数のincludeタイプを明示的に指定できます:

  include:
    - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'
    - local: 'templates/.after-script-template.yml'
    - template: Auto-DevOps.gitlab-ci.yml

• デフォルトと特定のincludeタイプを組み合わせた配列を定義できます:

  include:
    - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml'
    - 'templates/.after-script-template.yml'
    - template: Auto-DevOps.gitlab-ci.yml
    - project: 'my-group/my-project'
      ref: main
      file: 'templates/.gitlab-ci-template.yml'

インクルードされた設定ファイルのdefault設定を使用する

設定ファイルでdefaultセクションを定義できます。includeキーワードと組み合わせてdefaultセクションを使用する場合、パイプライン内のすべてのジョブにこのデフォルトが適用されます。

たとえば、before_scriptでdefaultセクションを使用できます。

カスタム設定ファイル/templates/.before-script-template.ymlの内容:

default:
  before_script:
    - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
    - gem install bundler --no-document
    - bundle install --jobs $(nproc)  "${FLAGS[@]}"

.gitlab-ci.ymlの内容:

include: 'templates/.before-script-template.yml'

rspec1:
  script:
    - bundle exec rspec

rspec2:
  script:
    - bundle exec rspec

デフォルトのbefore_scriptコマンドは、両方のrspecジョブでscriptコマンドの前に実行されます。

インクルードされた設定の値をオーバーライドする

includeキーワードを使用する場合、インクルードされた設定の値をオーバーライドして、パイプライン要件に適合させることができます。

次の例は、.gitlab-ci.ymlファイル内でカスタマイズされたincludeファイルを示しています。YAMLで定義した特定の変数と、productionジョブの詳細がオーバーライドされます。

カスタム設定ファイルautodevops-template.ymlの内容:

variables:
  POSTGRES_USER: user
  POSTGRES_PASSWORD: testing_password
  POSTGRES_DB: $CI_ENVIRONMENT_SLUG

production:
  stage: production
  script:
    - install_dependencies
    - deploy
  environment:
    name: production
    url: https://$CI_PROJECT_PATH_SLUG.$KUBE_INGRESS_BASE_DOMAIN
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

.gitlab-ci.ymlの内容:

include: 'https://company.com/autodevops-template.yml'

default:
  image: alpine:latest

variables:
  POSTGRES_USER: root
  POSTGRES_PASSWORD: secure_password

stages:
  - build
  - test
  - production

production:
  environment:
    url: https://domain.com

.gitlab-ci.ymlファイルで定義されたPOSTGRES_USER変数とPOSTGRES_PASSWORD変数、およびproductionジョブのenvironment:urlが、autodevops-template.ymlファイルで定義された値をオーバーライドします。他のキーワードは変更されません。この方法はマージと呼ばれます。

includeのマージ方法

include設定は、次のプロセスでメインの設定ファイルとマージされます:

• インクルードされたファイルは設定ファイルで定義された順に読み取られ、その設定は同じ順序でマージされます。
• インクルードされたファイルもincludeを使用している場合、そのネストされたinclude設定が最初に（再帰的に）マージされます。
• パラメータが重複している場合、インクルードされたファイルの設定をマージする際に、最後にインクルードされたファイルが優先されます。
• includeで追加されたすべての設定がマージされた後、インクルードされた設定とメインの設定がマージされます。

このマージ方法は_ディープマージ_と呼ばれ、ハッシュマップは設定内の任意の深さでマージされます。ハッシュマップ「A」（この時点までにマージ済みの設定を含む）と「B」（次にマージされる設定）をマージする場合、キーと値は次のルールで処理されます:

• キーがAにのみ存在する場合は、Aのキーと値を使用する。
• キーがAとBの両方に存在し、値が両方ともハッシュマップである場合は、それらのハッシュマップをマージする。
• キーがAとBの両方に存在し、どちらかの値がハッシュマップでない場合は、Bの値を使用する。
• それ以外の場合は、Bのキーと値を使用する。

たとえば、設定が次の2つのファイルで構成される場合:

• .gitlab-ci.ymlファイル:

  include: 'common.yml'
  
  variables:
    POSTGRES_USER: username
  
  test:
    rules:
      - if: $CI_PIPELINE_SOURCE == "merge_request_event"
        when: manual
    artifacts:
      reports:
        junit: rspec.xml

• common.ymlファイル:

  variables:
    POSTGRES_USER: common_username
    POSTGRES_PASSWORD: testing_password
  
  test:
    rules:
      - when: never
    script:
      - echo LOGIN=${POSTGRES_USER} > deploy.env
      - rake spec
    artifacts:
      reports:
        dotenv: deploy.env

マージされた結果:

variables:
  POSTGRES_USER: username
  POSTGRES_PASSWORD: testing_password

test:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual
  script:
    - echo LOGIN=${POSTGRES_USER} > deploy.env
    - rake spec
  artifacts:
    reports:
      junit: rspec.xml
      dotenv: deploy.env

この例では:

• 変数は、すべてのファイルがマージされた後にのみ評価されます。インクルードされたファイル内のジョブが、最終的に別のファイルで定義された変数の値を使用する場合があります。
• rulesは配列であるため、マージできません。トップレベルのファイルが優先されます。
• artifactsはハッシュマップであるため、ディープマージが可能です。

インクルードされた設定の配列をオーバーライドする

マージを使用すると、インクルードされたテンプレートの設定を拡張またはオーバーライドできますが、配列内の個別の項目を追加したり変更したりすることはできません。たとえば、拡張されたproductionジョブのscript配列にnotify_ownerコマンドを追加する場合、次のようになります:

autodevops-template.ymlの内容:

production:
  stage: production
  script:
    - install_dependencies
    - deploy

.gitlab-ci.ymlの内容:

include: 'autodevops-template.yml'

stages:
  - production

production:
  script:
    - install_dependencies
    - deploy
    - notify_owner

.gitlab-ci.ymlファイル内でinstall_dependenciesとdeployが再定義されていない場合、productionジョブのスクリプトにはnotify_ownerのみが残ります。

ネストされたインクルードを使用する

設定ファイル内のincludeセクションをネストし、その設定ファイルをさらに別の設定ファイルにインクルードできます。たとえば、includeキーワードを3階層にネストした場合、次のようになります:

.gitlab-ci.ymlの内容:

include:
  - local: /.gitlab-ci/another-config.yml

/.gitlab-ci/another-config.ymlの内容:

include:
  - local: /.gitlab-ci/config-defaults.yml

/.gitlab-ci/config-defaults.ymlの内容:

default:
  after_script:
    - echo "Job complete."

重複するincludeエントリがあるネストされたインクルードを使用する

同じ設定ファイルを、メインの設定ファイルとネストされたインクルードに複数回インクルードできます。

ファイルがオーバーライドを使用して、インクルードされた設定を変更する場合、includeエントリの順序が最終的な設定に影響を及ぼすことがあります。最後にインクルードされたときの設定が、それ以前の設定をオーバーライドします。次に例を示します:

• defaults.gitlab-ci.ymlファイルの内容:

  default:
    before_script: echo "Default before script"

• unit-tests.gitlab-ci.ymlファイルの内容:

  include:
    - template: defaults.gitlab-ci.yml
  
  default:  # Override the included default
    before_script: echo "Unit test default override"
  
  unit-test-job:
    script: unit-test.sh

• smoke-tests.gitlab-ci.ymlファイルの内容:

  include:
    - template: defaults.gitlab-ci.yml
  
  default:  # Override the included default
    before_script: echo "Smoke test default override"
  
  smoke-test-job:
    script: smoke-test.sh

上記の3つのファイルを使用する場合、インクルードする順序によって最終的な設定が変わります。次のようになります:

• unit-testsを最初にインクルードした場合の.gitlab-ci.ymlファイルの内容:

  include:
    - local: unit-tests.gitlab-ci.yml
    - local: smoke-tests.gitlab-ci.yml

  最終的な設定:

  unit-test-job:
   before_script: echo "Smoke test default override"
   script: unit-test.sh
  
  smoke-test-job:
   before_script: echo "Smoke test default override"
   script: smoke-test.sh

• unit-testsを最後にインクルードした場合の.gitlab-ci.ymlファイルの内容:

  include:
    - local: smoke-tests.gitlab-ci.yml
    - local: unit-tests.gitlab-ci.yml

• 最終的な設定:

  unit-test-job:
   before_script: echo "Unit test default override"
   script: unit-test.sh
  
  smoke-test-job:
   before_script: echo "Unit test default override"
   script: smoke-test.sh

インクルードされた設定をオーバーライドするファイルがない場合、includeエントリの順序は最終的な設定に影響しません。

includeで変数を使用する

.gitlab-ci.ymlファイルのincludeセクションでは、以下を使用できます:

• プロジェクト変数。
• グループ変数。
• インスタンス変数。
• プロジェクトの定義済み変数（CI_PROJECT_*）。
• トリガー変数。
• スケジュールされたパイプライン変数。
• 手動パイプライン実行変数。
• 定義済み変数CI_PIPELINE_SOURCEとCI_PIPELINE_TRIGGERED。
• 定義済み変数$CI_COMMIT_REF_NAME。

次に例を示します:

include:
  project: '$CI_PROJECT_PATH'
  file: '.compliance-gitlab-ci.yml'

ジョブ内で定義された変数や、すべてのジョブのデフォルト変数を定義するグローバルvariablesセクションで定義された変数は使用できません。インクルードはジョブの前に評価されるため、これらの変数をincludeで使用することはできません。

定義済み変数をインクルードする方法、それらの変数がCI/CDジョブに及ぼす影響の例については、このCI/CD変数のデモを参照してください。

動的な子パイプラインの設定のincludeセクションでは、CI/CD変数は使用できません。イシュー378717で、この問題の修正が提案されています。

rulesをincludeと組み合わせて使用する

rulesとincludeを組み合わせて使用すると、条件付きで他の設定ファイルをインクルードできます。

rulesを使用できるのは、特定の変数および以下のキーワードに限定されます:

• rules:if。
• rules:exists。
• rules:changes。

rules:ifをincludeと組み合わせる

rules:ifを使用すると、CI/CD変数の状態に基づいて、条件付きで他の設定ファイルをインクルードできます。次に例を示します:

include:
  - local: builds.yml
    rules:
      - if: $DONT_INCLUDE_BUILDS == "true"
        when: never
  - local: builds.yml
    rules:
      - if: $ALWAYS_INCLUDE_BUILDS == "true"
        when: always
  - local: builds.yml
    rules:
      - if: $INCLUDE_BUILDS == "true"
  - local: deploys.yml
    rules:
      - if: $CI_COMMIT_BRANCH == "main"

test:
  stage: test
  script: exit 0

rules:existsをincludeと組み合わせる

rules:existsを使用すると、ファイルの存在に基づいて、条件付きで他の設定ファイルをインクルードできます。次に例を示します:

include:
  - local: builds.yml
    rules:
      - exists:
          - exception-file.md
        when: never
  - local: builds.yml
    rules:
      - exists:
          - important-file.md
        when: always
  - local: builds.yml
    rules:
      - exists:
          - file.md

test:
  stage: test
  script: exit 0

この例では、GitLabは現在のプロジェクトにfile.mdが存在するかどうかを確認します。

別のプロジェクトからのインクルードファイルでrules:existsとともにincludeを使用する場合は、設定を慎重にレビューする必要があります。GitLabは、別のプロジェクトにファイルが存在するかどうかを確認します。次に例を示します:

# Pipeline configuration in my-group/my-project
include:
  - project: my-group/other-project
    ref: other_branch
    file: other-file.yml

test:
  script: exit 0

# other-file.yml in my-group/other-project on ref other_branch
include:
  - project: my-group/my-project
    ref: main
    file: my-file.yml
    rules:
      - exists:
          - file.md

この例では、GitLabは、パイプラインが実行されるプロジェクトや参照ではなく、other_branchのmy-group/other-projectのコミット参照でfile.mdが存在するかどうかを検索します。

検索コンテキストを変更するには、rules:exists:pathsをrules:exists:projectとともに使用します。次に例を示します:

include:
  - project: my-group/my-project
    ref: main
    file: my-file.yml
    rules:
      - exists:
          paths:
            - file.md
          project: my-group/my-project
          ref: main

rules:changesをincludeと組み合わせる

rules:changesを使用すると、変更されたファイルに基づいて、条件付きで他の設定ファイルをインクルードできます。次に例を示します:

include:
  - local: builds1.yml
    rules:
      - changes:
        - Dockerfile
  - local: builds2.yml
    rules:
      - changes:
          paths:
            - Dockerfile
          compare_to: 'refs/heads/branch1'
        when: always
  - local: builds3.yml
    rules:
      - if: $CI_PIPELINE_SOURCE == "merge_request_event"
        changes:
          paths:
            - Dockerfile

test:
  stage: test
  script: exit 0

この例では:

• Dockerfileが変更されている場合、builds1.ymlをインクルードします。
• refs/heads/branch1と比較して、Dockerfileが変更されている場合、builds2.ymlをインクルードします。
• Dockerfileが変更され、かつパイプラインソースがマージリクエストイベントである場合、builds3.ymlをインクルードします。builds3.ymlのジョブも、マージリクエストパイプラインで実行するように設定されている必要があります。

include:localでワイルドカードのファイルパスを使用する

include:localではワイルドカードパス（*および**）を使用できます。

例:

include: 'configs/*.yml'

パイプラインを実行すると、GitLabは次のように動作します:

• configsディレクトリ内のすべての.ymlファイルをパイプライン設定に追加します。

• configsディレクトリのサブフォルダーにある.ymlファイルは追加しません。これを許可するには、次の設定を追加します:

  # This matches all `.yml` files in `configs` and any subfolder in it.
  include: 'configs/**.yml'
  
  # This matches all `.yml` files only in subfolders of `configs`.
  include: 'configs/**/*.yml'

トラブルシューティング

Maximum of 150 nested includes are allowed!エラー

パイプラインで許可されるネストされたインクルードファイルの最大数は150です。パイプラインでMaximum 150 includes are allowedというエラーメッセージが表示される場合、次のいずれかが原因である可能性があります:

• ネストされた設定の一部に、過剰な数のネストされたinclude設定が含まれている。
• ネストされたインクルードに意図しないループが存在する。たとえば、include1.ymlがinclude2.ymlをインクルードし、それがinclude1.ymlをインクルードすることで再帰的なループが発生している。

この問題が発生するリスクを軽減するには、パイプラインエディタでパイプライン設定ファイルを編集します。エディタが、上限に達したかどうかを検証します。一度に1つずつインクルードファイルを削除すると、ループや過剰なインクルードファイルの原因となっている設定ファイルを絞り込めます。

GitLab 16.0以降 、GitLab Self-Managedのユーザーは、最大インクルード数の値を変更できるようになりました。

SSL_connect SYSCALL returned=5 errno=0 state=SSLv3/TLS write client helloおよびその他のネットワーク障害

include:remoteを使用する場合、GitLabはHTTP(S)を介してリモートファイルのフェッチを試行します。さまざまな接続に関する問題が原因で、このプロセスが失敗することがあります。

SSL_connect SYSCALL returned=5 errno=0 state=SSLv3/TLS write client helloエラーは、GitLabがリモートホストへのHTTPS接続を確立できない場合に発生します。この問題は、リクエストによるサーバーの過負荷を防ぐために、リモートホストにレート制限が設定されている場合に発生する可能性があります。

たとえば、GitLab.comのGitLab Pagesサーバーにはレート制限があります。GitLab PagesでホストされているCI/CD設定ファイルを繰り返しフェッチしようとすると、レート制限に達してエラーが発生する可能性があります。GitLab PagesサイトでCI/CD設定ファイルをホストするのは避けてください。

可能であれば、外部HTTP(S)リクエストを行わずに、include:projectを使用して、GitLabインスタンス内の他のプロジェクトから設定ファイルをフェッチします。