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

チュートリアル: CI/CDステップをセットアップする

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

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

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

  1. 「hello world」を出力するステップを作成します。
  2. ステップを使用するようにパイプラインを設定します。
  3. ジョブに複数のステップを追加します。
  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. .gitlab-ci.ymlファイルで、hello_stepsという別のステップをジョブに追加します:

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

    このhello_stepsステップでは、gitlab stepsに、デフォルトではないインプットwhoを指定しています。

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

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

    git commit -a -m 'Added another step'
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 steps
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 steps

    この新しいステップにはインプットがないため、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 step config'
git push
glab ci status

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

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

    $ /step-runner ci
hello world
hello gitlab steps
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 steps
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 steps"}
all my greetings say hello world and hello gitlab steps
Cleaning up project directory and file based variables
Job succeeded

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