正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

チュートリアル: CI/CD関数を設定する

このチュートリアルでは、パイプラインで関数を作成して使用する方法について説明します。

ステップは、ジョブの再利用可能でコンポーザブルな要素です。各関数は、他の関数で使用できる構造化された入力と出力を定義します。関数は、ローカルファイル、GitLab.comリポジトリ、またはその他のGitソースで設定できます。

このチュートリアルでは、GitLab CLI（glab）を使用して次の手順を実行します:

  1. 「Hello, World」を出力する関数を作成します。
  2. 関数を使用するようにパイプラインを設定します。
  3. 1つのジョブに複数の関数を追加します。
  4. リモート関数を使用して、echoコマンドで出力をすべて表示します。

はじめる前

  • GitLab CLI（glab）をインストールしてサインインする必要があります。

関数を作成する

まず、次の関数を作成します:

  • execタイプ。
  • システムのexecutive APIによって開始されるcommand。

  1. ネームスペースにzero-to-stepsという名前のGitLabプロジェクトを作成します:

    glab project create zero-to-steps

  2. プロジェクトリポジトリのルートに移動します:

    cd zero-to-steps

  3. step.ymlファイルを作成します。

    touch step.yml

  4. テキストエディタを使用して、step.ymlに仕様を追加します:

    spec:
  inputs:
    who:
      type: string
      default: world
    • specには、whoという名前の入力が1つあります。
    • デフォルト値があるため、入力whoはオプションです。

  5. step.ymlに実装を追加するには、specの後に、execキーを指定した2番目のYAMLドキュメントを追加します:

    spec:
  inputs:
    who:
      type: string
      default: world
---
exec:
  command:
    - bash
    - -c
    - echo 'hello ${{inputs.who}}'

3連続のemダッシュ（---）は、ファイルを2つのYAMLドキュメントに区切るための記号です:

  • 最初のドキュメントは仕様で、関数シグネチャのようなものです。
  • 2番目のドキュメントは実装で、関数本体のようなものです。

bashと-cの引数はBash Shellを起動し、コマンドライン引数からスクリプトインプットを受け取ります。Shellスクリプトに加えて、commandを使用して、dockerやterraformなどのプログラムを実行できます。

echo 'hello ${{input.name}}'引数には、${{と}}の内側に式が含まれています。式は可能な限り最後の瞬間に評価され、現在の実行コンテキストにアクセスできます。この式はinputsにアクセスし、whoの値を読み取ります:

  • 呼び出し元によってwhoが指定されている場合、その値が式に代入されます。
  • whoが省略されている場合、デフォルトのworldが式に代入されます。

関数を使用するようにパイプラインを設定する

  1. リポジトリのルートに、.gitlab-ci.ymlファイルを作成します:

    touch .gitlab-ci.yml

  2. .gitlab-ci.ymlで、次のジョブを追加します:

    hello-world:
  run:
    - name: hello_world
      step: .
    • runキーワードには、関数呼び出しのリストがあります。
      • 各呼び出しにはnameが与えられるため、以降の関数で出力を参照できます。
      • 各呼び出しでは、実行するstepを指定します。ローカル参照（.）は、リポジトリのルートを指します。

    このコードがリポジトリでどのように表示されるかの例については、ステップのチュートリアル、パート1を参照してください。

  3. 両方のファイルをコミットし、プロジェクトリポジトリをプッシュします。これにより、ジョブを実行するパイプラインがトリガーされます:

    git add .
git commit -m 'Part 1 complete'
git push --set-upstream origin main
glab ci status

  4. パイプラインが完了するまで、「ログの表示」でジョブを追跡します。成功したジョブの例を次に示します:

    Step Runner version: a7c7c8fd
See https://gitlab.com/gitlab-org/step-runner/-/blob/main/CHANGELOG.md for changes.
...
hello world
Cleaning up project directory and file based variables
Job succeeded

これで、最初の関数を作成して使用できました。

1つのジョブに複数の関数を追加する

1つのジョブに複数の関数を含めることができます。

  1. .gitlab-ci.ymlファイルで、hello_stepsという別の関数をジョブに追加します:

    hello-world:
  run:
    - name: hello_world
      step: .
    - name: hello_steps
      step: .
      inputs:
        who: gitlab functions

    このhello_steps関数では、gitlab functionsに、デフォルトではない入力whoを指定しています。

    このコードがリポジトリでどのように表示されるかの例については、ステップのチュートリアル、パート2aを参照してください。

  2. 変更をコミットしてプッシュします:

    git commit -a -m 'Added another function'
git push
glab ci status

  3. ターミナルで、ログの表示を選択し、完了するまでパイプラインを追跡します。成功した出力の例を次に示します:

    Step Runner version: a7c7c8fd
See https://gitlab.com/gitlab-org/step-runner/-/blob/main/CHANGELOG.md for changes.
...
hello world
hello gitlab functions
Cleaning up project directory and file based variables
Job succeeded

関数をリファクタリングする

関数をリファクタリングするには、関数を.gitlab-ci.ymlから専用ファイルに移動します:

  1. 最初に作成した関数をhelloというディレクトリに移動します:

    mkdir hello
mv step.yml hello/

  2. リポジトリのルートに新しい関数を作成します。

    touch step.yml

  3. 次の設定を新しいstep.ymlに追加します:

    spec:
---
run:
  - name: hello_world
    step: ./hello
  - name: hello_steps
    step: ./hello
    inputs:
      who: gitlab functions

    この新しい関数には入力がないため、specは空です。これはstepsタイプで、.gitlab-ci.ymlの関数と同じ構文を持ちます。ただし、ローカル参照は、helloディレクトリ内の関数を指すようになりました。

  4. 新しい関数を使用するには、.gitlab-ci.ymlを変更します:

    hello-world:
  run:
    - name: hello_everybody
      step: .

    これで、ジョブは入力なしで新しい関数のみを呼び出します。ジョブの詳細を別のファイルにリファクタリングできました。

    このコードがリポジトリでどのように表示されるかの例については、ステップのチュートリアル、パート2bを参照してください。

  5. 変更をコミットしてプッシュします:

    git add .
git commit -m 'Refactored function config'
git push
glab ci status

  6. ターミナルで、ログの表示を選択します。

  7. リファクタリングされた関数が最初に作成した関数と同じ関数を実行することを確認するには、ログ出力を表示します。ログ出力は、以前に作成した関数の出力と一致するはずです。次に例を示します:

    $ /step-runner ci
hello world
hello gitlab functions
Cleaning up project directory and file based variables
Job succeeded

関数に出力を追加する

hello関数に出力を追加します。

  1. hello/step.ymlで、outputs構造をspecに追加します:

    spec:
  inputs:
    who:
      type: string
      default: world
  outputs:
    greeting:
      type: string
---
exec:
  command:
    - bash
    - -c
    - echo '{"name":"greeting","value":"hello ${{inputs.who}}"}' | tee ${{output_file}}
    • このspecでは、デフォルトなしで1つの出力greetingを定義しました。デフォルトがないため、出力greetingが必要です。
    • 出力は、実行時に提供されるJSON Lines形式の${{output_file}}ファイルに書き込まれます。出力ファイルに書き込まれる各行は、2つのキー（nameとvalue）を持つJSONオブジェクトである必要があります。
    • この関数はecho '{"name":"greeting","value":"hello ${{inputs.who}}"}'を実行し、出力をジョブログと出力ファイル（tee ${{output_file}}）に送信します。

  2. step.ymlで、ステップに出力を追加します:

    spec:
  outputs:
    all_greetings:
      type: string
---
run:
  - name: hello_world
    step: ./hello
  - name: hello_steps
    step: ./hello
    inputs:
      who: gitlab functions
outputs:
  all_greetings: "${{steps.hello_world.outputs.greeting}} and ${{steps.hello_steps.outputs.greeting}}"

    これで、all_greetingsという名前の出力をこの関数に追加できました。

    この出力は、式構文${{steps.hello_world.outputs.greeting}}を示しています。all_greetingsは、2つのサブステップhello_worldとhello_stepsの出力を読み取ります。両方のサブステップの出力が連結されて、1つの文字列出力になります。

リモート関数を使用する

コードをコミットして実行する前に、ジョブに別の関数を追加して、メインのstep.ymlの最終的なall_greetingsの出力を確認します。

この関数の呼び出しは、echo-stepという名前のリモート関数を参照します。echo関数は、1つのインプットechoを受け取り、その値をログに出力し、echoとして出力します。

  1. .gitlab-ci.ymlを編集します:

    hello-world:
  run:
    - name: hello_everybody
      step: .
    - name: all_my_greetings
      step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@main
      inputs:
        echo: "all my greetings say ${{steps.hello_everybody.outputs.all_greetings}}"

    このコードがリポジトリでどのように表示されるかの例については、ステップのチュートリアル、パート2cを参照してください。

  2. 変更をコミットしてプッシュします:

    git commit -a -m 'Added outputs'
git push
glab ci status

  3. パイプラインが完了するまで、「ログの表示」でジョブを追跡します。成功した出力の例を次に示します:

    Step Runner version: a7c7c8fd
See https://gitlab.com/gitlab-org/step-runner/-/blob/main/CHANGELOG.md for changes.
...
{"name":"greeting","value":"hello world"}
{"name":"greeting","value":"hello gitlab functions"}
all my greetings say hello world and hello gitlab functions
Cleaning up project directory and file based variables
Job succeeded

以上です。パイプラインで関数を作成し、実装できました。関数の構文の詳細については、CI/CD関数を参照してください。