他のファイルからCI/CD設定を使用

include を使って CI/CD ジョブに外部の YAML ファイルを含めることができます。

1つの設定ファイルをインクルードします

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

  • include を単独で使用します。これが内部ファイルの場合は、include:local と同じです。リモート・ファイルの場合は、include:remote と同じです。

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

設定ファイルの配列をインクルードします。

設定ファイルの配列を含めることができます：

  • 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 セクションを使用すると、デフォルトがパイプライン内のすべてのジョブに適用されます。

例えば、default セクションをbefore_script.

/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 コマンドは、script コマンドの前に、rspec ジョブの両方で実行されます。

含まれる設定値の上書き

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

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

のマージメソッドinclude

include 設定はこの処理でメイン設定ファイルにマージされます：

  • インクルードされたファイルは設定ファイルで定義された順番で読み込まれ、インクルードされた設定は同じ順番でマージされます。
  • インクルードされたファイルが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

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

ネストされたインクルードを使います

include 設定ファイルのセクションを includeネストしてinclude 、別の設定に include含めることができます。例えば、キーワードが3つネストしているinclude 場合 include：

.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."

includes 、重複する内部インクルードを使用します。

GitLab 14.8 で導入されました。

ネストされたインクルードは同じ設定ファイルをインクルードすることができます。重複した設定ファイルは複数回インクルードされますが、その効果は一度だけインクルードされた場合と同じです。

たとえば、defaults.gitlab-ci.yml が複数回インクルードされている場合、次のように入れ子になります：

  • .gitlab-ci.yml ファイルの内部：

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

  • defaults.gitlab-ci.yml ファイルの内部：

     default:
   before_script: default-before-script.sh
   retry: 2

  • unit-tests.gitlab-ci.yml ファイルの内部：

     include:
   - template: defaults.gitlab-ci.yml
   
 unit-test-job:
   script: unit-test.sh
   retry: 0

  • smoke-tests.gitlab-ci.yml ファイルの内部：

     include:
   - template: defaults.gitlab-ci.yml
   
 smoke-test-job:
   script: smoke-test.sh

最終的な設定は次のようになります：

unit-test-job:
  before_script: default-before-script.sh
  script: unit-test.sh
  retry: 0

smoke-test-job:
  before_script: default-before-script.sh
  script: smoke-test.sh
  retry: 2

変数をinclude

.gitlab-ci.yml ファイルのinclude セクションで使用できます：

GitLab 14.5以降では、次のように使うこともできます：

使用例：

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

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

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

rules 。include

  • GitLab 14.2 でci_include_rules というフラグで導入されました。デフォルトでは無効です。
  • GitLab.comでは有効、GitLab 14.3では自己管理。
  • GitLab 14.4で一般的に利用可能に。機能フラグci_include_rules を削除しました。
  • GitLab 14.5で exists キーワードをサポート。
  • GitLab 15.11 で導入されたneeds ジョブ依存性のサポート。

include と一緒にrules を使うことで、他の設定ファイルを条件付きでインクルードすることができます。

rules を使用できるのは、特定の変数とこれらのキーワードだけです：

include とともにrules:if

  • GitLab 16.1 で導入された when: never とwhen:always のサポートはci_support_include_rules_when_never というフラグで行います。デフォルトでは無効になっています。
  • when: never とwhen:always のサポートはGitLab 16.2で一般的に利用可能。機能フラグci_support_include_rules_when_never を削除しました。

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

include とともにrules:exists

  • GitLab 16.1 で導入された when: never とwhen:always のサポートはci_support_include_rules_when_never というフラグで行います。デフォルトでは無効になっています。
  • when: never とwhen:always のサポートはGitLab 16.2で一般的に利用可能。機能フラグci_support_include_rules_when_never を削除しました。

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は_他の_プロジェクトにファイルが存在するかチェックします。例えば

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

test:
  stage: test
  script: exit 0

この例では、GitLabは現在のプロジェクトではなく、my-group/my-project-2 にあるtest-file.yml の存在をチェックします。この動作を改善するための作業については、イシュー386040に従ってください。

include とともにrules:changes

GitLab 16.4 でci_support_include_rules_changesというフラグで 導入された rules:changes のサポート。デフォルトでは無効になっています。

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

この例では:

  • builds1.yml は、Dockerfile が変更された場合に含まれます。
  • builds2.yml は、Dockerfile がrefs/heads/branch1に対して相対的に変更された場合に含まれます。
  • builds3.yml は、Dockerfile が変更され、パイプラインソースがマージリクエストイベントである場合に含まれます。

ワイルドカードファイルパスで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'

include で追加された設定の入力を定義します。

GitLab 15.11でベータ機能として導入されました。

フラグ:spec とwith は実験的なオープンベータ機能であり、予告なく変更される場合があります。

入力パラメータをspec:inputs

include でパイプラインに追加する CI/CD 設定の入力パラメータを定義するにはspec:inputs を使用します。include:inputs を使用して、パイプラインの実行時に使用する値を定義します。

specは設定ファイルの先頭、ヘッダーセクションで宣言する必要があります。ヘッダーは--- で残りの設定から分離します。

ヘッダーセクションの外部で値を参照するには、補間フォーマット$[[ input.input-id ]] を使用します。入力の評価と補間は、パイプラインの作成中に設定が取得されるときに一度だけ行われますが、設定が.gitlab-ci.yml の内容とマージされる前に行われます。

spec:
  inputs:
    environment:
    job-stage:
---

scan-website:
  stage: $[[ inputs.job-stage ]]
  script: ./scan-website $[[ inputs.environment ]]

spec:inputs ：

  • 定義された入力はデフォルトで必須です。
  • 入力は、default を指定することでオプションにすることができます。 デフォルト値を指定しない場合は、default: null を使用します。
  • 補間ブロックを含む文字列は1MBを超えてはいけません。
  • 補間ブロック内の文字列は1KBを超えてはいけません。

例えば、custom_configuration.yml ：

spec:
  inputs:
    website:
    user:
      default: 'test-user'
    flags:
      default: null
---

# The pipeline configuration would follow...

この例では:

  • website は必須で、必ず定義しなければなりません。
  • user はオプションです。定義されていない場合、値はtest-user になります。
  • flags は省略可能です。定義されていない場合、値はありません。

入力値を操作する関数の指定

GitLab 16.3 で導入されました。

補間ブロックの中で定義済みの関数を指定し、入力値を操作することができます。サポートされているフォーマットは以下の通りです：

$[[ input.input-id | <function1> | <function2> | ... <functionN> ]]

詳細

spec:
  inputs:
    test:
      default: '0123456789'
---

test-job:
  script: echo $[[ inputs.test | truncate(1,3) ]]

この例では:

  • 関数truncate はinputs.testの値に適用されます。
  • inputs.test の値を0123456789 とすると、script の出力はecho 123となります。

定義済みの補間関数

切り捨て

truncate を使って補間値を短くします。例えば

  • truncate(<offset>,<length>)
名前種類説明
offset整数オフセットする文字数。
length整数オフセットの後に返す文字数。

使用例：

$[[ inputs.test | truncate(3,5) ]]

inputs.test の値を0123456789 とすると、出力は34567となります。

入力パラメータ値をinclude:inputs

include:with GitLab 16.0ではinclude:inputs に改名されました。

include:inputs を使って、インクルードされた設定がパイプラインに追加される際にパラメータの値を設定します。

例えば、上記の例と同じ仕様のcustom_configuration.yml をインクルードする場合：

include:
  - local: 'custom_configuration.yml'
    inputs:
      website: "My website"

この例では:

  • website にはMy website という値が含まれています。
  • user の値はtest-user で、これは指定されていない場合のデフォルトだからです。
  • flags は値を持ちません。これは省略可能で、指定されない場合のデフォルトがないからです。

複数のファイルでinclude:inputs を使用します。

inputs は、インクルードされるファイルごとに個別に指定する必要があります。例えば

include:
  - component: gitlab.com/org/my-component@1.0
    inputs:
      stage: my-stage
  - local: path/to/file.yml
    inputs:
      stage: my-stage

同じファイルを異なる入力で複数回インクルードすることもできます。例えば

include:
  - local: path/to/my-super-linter.yml
    inputs:
      type: docs
      job-name: lint-docs
      lint-path: "doc/"
  - local: path/to/my-super-linter.yml
    inputs:
      type: yaml
      job-name: lint-yaml
      lint-path: "data/yaml/"

トラブルシューティング

Maximum of 150 nested includes are allowed! エラー

パイプラインのネストされたインクルードファイルの最大数は150です。パイプラインでMaximum 150 includes are allowed のエラーメッセージが表示される場合は、次のいずれかが考えられます：

  • ネストされた設定の一部に、include 追加のネストされた設定が過度に多く含まれています。
  • ネストされたincludeに偶発的なループがあります。例えば、include1.yml はinclude2.yml をインクルードし、その はinclude1.ymlをインクルードし、再帰ループを作成します。

このようなことが起こるリスクを減らすために、パイプラインエディターでパイプライン設定ファイルを編集します。一度に1つのインクルードファイルを削除して、どの設定ファイルがループや過剰なインクルードファイルの原因かを絞り込むことができます。

GitLab 16.0以降のセルフマネージドユーザーは、インクルードファイルの最大値を変更することができます。