GitLab CI/CD関数

GitLab CI/CD関数は、ジョブの再利用可能なユニットであり、まとめて構成すると、GitLab CI/CDジョブで使用されるscriptを置き換えます。関数を使用する必要はありません。ただし、関数の再利用性、構成可能性、テスト容易性、および独立性により、CI/CDパイプラインを理解および維持しやすくなります。

まず、関数のセットアップチュートリアルをお試しください。独自の関数の作成を開始するには、独自の関数の作成を参照してください。CI/CDコンポーネントとCI/CD関数の両方を使用することから、パイプラインがどのようにメリットを得られるかを理解するには、CI/CDコンポーネントとCI/CD関数の組み合わせを参照してください。

この実験的機能はまだ活発に開発されており、いつでも破壊的な変更が発生する可能性があります。破壊的な変更の詳細については、変更履歴を確認してください。

関数ワークフロー

関数は、関数のシーケンスを実行するか、コマンドを呼び出すかのいずれかです。各関数は入力と出力を指定し、CI/CDジョブ変数、環境変数、およびファイルシステムやネットワーキングなどのリソースにアクセスできます。関数は、ファイルシステム上、GitLab.comのリポジトリ、またはその他のGitソースにローカルでホストされます。

さらに、関数は次のようになります:

• GitLab Runnerチームによって作成されたDockerコンテナで実行されます。Dockerfileを確認できます。エピック15073を追跡して、CI/CDジョブで定義された実行環境内で関数がいつ実行されるかを追跡します。
• Linuxに固有です。エピック15074を追跡して、関数が複数のオペレーティングシステムをいつサポートするかを追跡します。

たとえば、このジョブはrun CI/CDキーワードを使用して関数を実行します:

job:
  variables:
    CI_SAY_HI_TO: "Sally"
  run:
    - name: say_hi
      step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@v1.0.0
      inputs:
        message: "hello, ${{job.CI_SAY_HI_TO}}"

このジョブを実行すると、メッセージhello, Sallyがジョブログに出力されます。echo関数の定義は次のとおりです:

spec:
  inputs:
    message:
      type: string
---
exec:
  command:
    - bash
    - -c
    - echo '${{inputs.message}}'

CI/CD関数を使用する

runキーワードを使用して、関数を使用するようにGitLab CI/CDジョブを構成します。CI/CD関数を実行している場合、ジョブでbefore_script、after_script、またはscriptを使用することはできません。

runキーワードは、実行する関数のリストを受け入れます。関数は、リストで定義されている順序で一度に1つずつ実行されます。各リスト項目にはnameと、step、script、またはactionのいずれかを指定します。

名前は英数字とアンダースコアのみで構成する必要があり、先頭を数字にすることはできません。

関数を実行する

stepキーワードを使用して、関数の場所を指定して、関数を実行します。

入力と環境変数を関数に渡すことができ、これらには値を補間する式を含めることができます。関数は、CI_PROJECT_DIR 事前定義変数によって定義されたディレクトリで実行されます。

たとえば、Gitリポジトリgitlab.com/components/echoから読み込むecho関数は、環境変数USER: Fredと入力message: hello Sallyを受け取ります:

job:
  variables:
    CI_SAY_HI_TO: "Sally"
  run:
    - name: say_hi
      step: gitlab.com/components/echo@v1.0.0
      env:
        USER: "Fred"
      inputs:
        message: "hello ${{job.CI_SAY_HI_TO}}"

スクリプトを実行する

scriptキーワードを使用して、Shellでスクリプトを実行します。envを使用してスクリプトに渡される環境変数は、Shellに設定されます。CI_PROJECT_DIR 事前定義変数によって定義されたディレクトリで、スクリプト関数が実行されます。

たとえば、次のスクリプトは、GitLabユーザーをジョブログに出力します:

my-job:
  run:
    - name: say_hi
      script: echo hello ${{job.GITLAB_USER_LOGIN}}

スクリプト関数はbashシェルを使用し、bashが見つからない場合はフォールバックしてshを使用します。

関数の場所

関数は、ファイルシステム上の相対パス、GitLab.comリポジトリ、またはその他のGitソースから読み込むことができます。

ファイルシステムから関数を読み込む

ピリオド.で始まる相対パスを使用して、ファイルシステムから関数を読み込むます。パスによって参照されるフォルダーには、step.yml関数定義ファイルが含まれている必要があります。パスセパレータは、オペレーティングシステムに関係なく、常にフォワードスラッシュ/を使用する必要があります。

例:

- name: my-step
  step: ./path/to/my-step

Gitリポジトリから関数を読み込む

リポジトリのURLとリビジョン（コミット、ブランチ、またはタグ）を指定して、Gitリポジトリから関数を読み込むます。リポジトリのstepsフォルダーにある関数の相対ディレクトリとファイル名を指定することもできます。ディレクトリを指定せずにURLを指定すると、stepsフォルダー内のstep.ymlが読み込まれます。

例:

• ブランチを使用して関数を指定します:

  job:
    run:
      - name: specifying_a_branch
        step: gitlab.com/components/echo@main

• タグを使用して関数を指定します:

  job:
    run:
      - name: specifying_a_tag
        step: gitlab.com/components/echo@v1.0.0

• リポジトリ内のディレクトリ、ファイル名、およびGitコミットを使用して関数を指定します:

  job:
    run:
      - name: specifying_a_directory_file_and_commit_within_the_repository
        step: gitlab.com/components/echo/-/reverse/my-step.yml@3c63f399ace12061db4b8b9a29f522f41a3d7f25

stepsフォルダー以外のフォルダーまたはファイルを指定するには、拡張されたstep構文を使用します:

• リポジトリルートに対する相対的なディレクトリとファイル名を指定します。

  job:
    run:
      - name: specifying_a_directory_outside_steps
        step:
          git:
            url: gitlab.com/components/echo
            rev: main
            dir: my-steps/sub-directory  # optional, defaults to the repository root
            file: my-step.yml            # optional, defaults to `step.yml`

式

式は、二重中括弧${{ }}で囲まれたミニ言語です。式は、ジョブ環境での関数の実行直前に評価され、次で使用できます:

• 入力値
• 環境変数値
• 関数の場所URL
• 実行可能コマンド
• 実行可能作業ディレクトリ
• 関数のシーケンスでの出力
• script関数
• action関数

式は、次の変数を参照できます:

式は、二重角括弧（$[[ ]]）を使用するテンプレート補間とは異なり、ジョブの生成時に評価されます。

式は、名前がCI_、DOCKER_、GITLAB_で始まるCI/CDジョブ変数にのみアクセスできます。エピック15073を追跡して、関数がすべてのCI/CDジョブ変数にアクセスできるタイミングを追跡します。

以前の関数の出力の使用

関数の入力は、関数名と出力変数名を参照することにより、以前の関数からの出力を参照できます。

たとえば、gitlab.com/components/random-string関数がrandom_valueという出力変数を定義した場合:

job:
  run:
    - name: generate_rand
      step: gitlab.com/components/random
    - name: echo_random
      step: gitlab.com/components/echo
      inputs:
        message: "The random value is: ${{steps.generate_rand.outputs.random_value}}"

環境変数

関数は設定環境変数をエクスポートし、環境変数は、step、script、またはactionを使用するときに渡すことができます。

環境変数は、次のリストに示す設定方法のうち、上にあるものほど優先順位が高くなります:

1. step.yml内でenvキーワードを使用して設定された変数。
2. 関数のシーケンスで関数に渡されるenvキーワードを使用します。
3. シーケンス内のすべての関数にenvキーワードを使用します。
4. 以前に実行された関数が${{export_file}}に書き込んだ場所。
5. Runnerによって設定された変数。
6. コンテナによって設定された変数。

独自の関数を作成する

独自の関数を作成するには、次のタスクを実行します:

1. CI/CDジョブの実行時にアクセス可能なGitLabプロジェクト、Gitリポジトリ、またはファイルシステム上のディレクトリを作成します。
2. step.ymlファイルを作成し、プロジェクト、リポジトリ、またはディレクトリのルートフォルダーに配置します。
3. step.ymlで関数の仕様を定義します。
4. step.ymlで関数の定義を定義します。
5. 関数が使用するファイルをプロジェクト、リポジトリ、またはディレクトリに追加します。

関数の作成後、ジョブで関数を使用できます。

関数仕様

関数仕様は、関数step.ymlに含まれる2つのドキュメントの1つです。仕様は、関数が受信および返す入力と出力を定義します。

入力を指定する

入力名には英数字とアンダースコアのみを使用でき、先頭を数字にすることはできません。入力には型を指定する必要があり、オプションでデフォルト値を指定できます。デフォルト値のない入力は必須入力であり、関数を使用するときに指定する必要があります。

入力は、次のいずれかの型である必要があります。

たとえば、関数がstring型のオプションの入力greetingを受け入れることを指定するには、次のようにします:

spec:
  inputs:
    greeting:
      type: string
      default: "hello, world"
---

ステップを使用するときに入力を提供するには、次のようにします:

run:
  - name: my_step
    step: ./my-step
    inputs:
      greeting: "hello, another world"

出力を指定する

入力と同様に、出力名には英数字とアンダースコアのみを使用でき、先頭を数字にすることはできません。出力には型を指定する必要があり、オプションでデフォルト値を指定できます。関数が出力を返さない場合、デフォルト値が返されます。

出力は、次のいずれかの型である必要があります。

たとえば、関数がnumber型のvalueという出力を返すように指定するには、次のようにします:

spec:
  outputs:
    value:
      type: number
---

ステップを使用するときに出力を使用するには、次のようにします:

run:
  - name: random_generator
    step: ./random_gen
  - name: echo_number
    step: ./echo
    inputs:
      message: "Random number generated was ${{step.random_generator.outputs.value}}"

委任された出力を指定する

出力名と型を指定する代わりに、出力を特定のステップに完全に委任できます。ステップによって返される出力は、関数によって返されます。関数定義のdelegateキーワードは、関数によって返されるステップ出力を決定します。

たとえば、次の関数は、random_gen関数によって返される出力を返します。

spec:
  outputs: delegate
---
run:
  - name: random_generator
    step: ./random_gen
delegate: random_generator

入力または出力を指定しない

関数は、入力を必要としないか、出力を返さない場合があります。これは、関数がディスクに書き込むか、環境変数を設定するか、STDOUTに出力するだけの場合に発生する可能性があります。この場合、spec:は次のように空になります:

spec:
---

関数定義

関数は次のことができます:

• 環境変数を設定する
• コマンドを実行する。
• 他の関数のシーケンスを実行します。

環境変数を設定する

envキーワードを使用して環境変数を設定します。環境変数名には英数字とアンダースコアのみを使用でき、先頭を数字にすることはできません。

環境変数は、実行可能コマンド、または関数のシーケンスを実行している場合はすべての関数で使用できるようになります。例:

spec:
---
env:
  FIRST_NAME: Sally
  LAST_NAME: Seashells
run:
  # omitted for brevity

関数は、ランナー環境から環境変数のサブセットにのみアクセスできます。エピック15073を追跡して、関数がすべての環境変数にアクセスできるタイミングを追跡します。

コマンドを実行する

関数は、execキーワードを使用してコマンドを実行することを宣言します。コマンドは必須ですが、作業ディレクトリ（work_dir）はオプションです。関数によって設定された環境変数は、実行中のプロセスで使用できます。

たとえば、次の関数は、関数ディレクトリをジョブログに出力します:

spec:
---
exec:
  work_dir: ${{step_dir}}
  command:
    - bash
    - -c
    - "echo ${PWD}"

出力を返す

実行可能関数は、JSON行形式で${{output_file}}に行を追加することにより、出力を返します。各行は、nameとvalueのキーペアを持つJSONオブジェクトです。nameは文字列でなければならず、valueは関数仕様の出力の種類と一致する型でなければなりません:

たとえば、string値Range Roverを持つcarという名前の出力を返すには、次のようにします:

spec:
  outputs:
    car:
      type: string
---
exec:
  command:
    - bash
    - -c
    - echo '{"name":"car","value":"Range Rover"}' >${{output_file}}

環境変数をエクスポートする

実行可能関数は、JSON行形式で${{export_file}}に行を追加することにより、環境変数をエクスポートします。各行は、nameとvalueのキーペアを持つJSONオブジェクトです。nameとvalueはどちらも文字列である必要があります。

たとえば、変数GOPATHに値/goを設定するには、次のようにします:

spec:
---
exec:
  command:
    - bash
    - -c
    - echo '{"name":"GOPATH","value":"/go"}' >${{export_file}}

関数のシーケンスを実行する

関数は、stepsキーワードを使用して関数のシーケンスを実行することを宣言します。関数は、リストで定義されている順序で一度に1つずつ実行されます。この構文は、runキーワードと同じです。

関数には、英数字とアンダースコアのみで構成される名前が必要であり、数字で始めてはなりません。

たとえば、この関数はGoをインストールしてから、Goが既にインストールされていることを前提とする2番目の関数を実行します:

spec:
---
run:
  - name: install_go
    step: ./go-steps/install-go
    inputs:
      version: "1.22"
  - name: format_go_code
    step: ./go-steps/go-fmt
    inputs:
      code: path/to/go-code

出力を返す

出力は、outputsキーワードを使用して関数のシーケンスから返されます。出力の値の型は、関数仕様の出力の型と一致する必要があります。

たとえば、次の関数は、インストールされているJavaバージョンを出力として返します。これは、install_java関数がjava_versionという名前の出力を返すことを前提としています。

spec:
  outputs:
    java_version:
      type: string
---
run:
  - name: install_java
    step: ./common/install-java
outputs:
  java_version: "the java version is ${{steps.install_java.outputs.java_version}}"

または、delegateキーワードを使用してサブステップのすべての出力を返すこともできます。例:

spec:
  outputs: delegate
---
run:
  - name: install_java
    step: ./common/install-java
delegate: install_java

CI/CDコンポーネントとCI/CD関数の組み合わせ

CI/CDコンポーネントは、再利用可能な単一のパイプライン設定ユニットです。パイプラインの作成時に組み込まれ、それらのコンポーネントによってジョブや設定がパイプラインに追加されます。コンポーネントプロジェクトの共通スクリプトやプログラムなどのファイルは、CI/CDジョブから参照できません。

CI/CD関数は、ジョブの再利用可能なユニットです。ジョブを実行すると、参照される関数が実行環境またはイメージにダウンロードされ、関数に含まれる追加ファイルが取り込まれます。関数の実行は、ジョブのscriptを置き換えます。

コンポーネントと関数は連携して、CI/CDパイプラインのソリューションを作成します。関数はジョブの構成方法の複雑さを処理し、ジョブの実行に必要なファイルを自動的に取得するます。コンポーネントを使用するとジョブの設定をインポートできますが、その内部的な構成はユーザーからは見えません。

関数とコンポーネントは、式の構文を区別するために、異なる式構文を使用します。コンポーネントの式では角括弧$[[ ]]を使用し、パイプラインの作成時に評価されます。関数式は中かっこ${{ }}を使用し、関数の実行直前にジョブの実行中に評価されます。

たとえば、プロジェクトで、Goコードを整形するジョブを追加するコンポーネントを使用できるとします:

• プロジェクトの.gitlab-ci.ymlファイルでは、次のようになります:

  include:
  - component: gitlab.com/my-components/go@main
    inputs:
      fmt_packages: "./..."

• 内部的には、コンポーネントはCI/CD関数を使用してジョブを構成し、Goをインストールしてからフォーマッタを実行します。コンポーネントのtemplates/go.ymlファイルでは、次のようになります:

  spec:
    inputs:
      fmt_packages:
        description: The Go packages that will be formatted using the Go formatter.
      go_version:
        default: "1.22"
        description: The version of Go to install before running go fmt.
  ---
  
  format code:
    run:
      - name: install_go
        step: ./languages/go/install
        inputs:
          version: $[[ inputs.go_version ]]                    # version set to the value of the component input go_version
      - name: format_code
        step: ./languages/go/go-fmt
        inputs:
          go_binary: ${{ steps.install_go.outputs.go_binary }} # go_binary set to the value of the go_binary output from the previous function
          fmt_packages: $[[ inputs.fmt_packages ]]             # fmt_packages set to the value of the component input fmt_packages

この例では、CI/CDコンポーネントは、コンポーネントの作成者から関数の複雑さを隠しています。

トラブルシューティング

HTTPS URLから関数をフェッチする

tls: failed to verify certificate: x509: certificate signed by unknown authorityなどのエラーメッセージは、オペレーティングシステムが関数をホストしているサーバーを認識または信頼していないことを示しています。

一般的な原因は、信頼できるルート証明書がインストールされていないDockerイメージを使用して、ジョブで関数が実行される場合です。コンテナに証明書をインストールするか、ジョブimageに組み込むことで、問題を解決できます。

script関数を使用して、関数をフェッチする前に、コンテナに依存関係をインストールできます。例:

ubuntu_job:
  image: ubuntu:24.04
  run:
    - name: install_certs  # Install trusted certificates first
      script: apt update && apt install --assume-yes --no-install-recommends ca-certificates
    - name: echo_step      # With trusted certificates, use HTTPS without errors
      step: https://gitlab.com/user/my_steps/hello_world@main