Step bundles

Stepバンドルを使用すると、複数のStepsを1つの単位にグループ化できます。Step bundlesを使用すると、YAML設定ファイルから手動でコピー&ペーストすることなく、StepsやStepsのシーケンスを再利用できます。

Step bundlesは、step_bundlesと呼ばれるルートレベルのエンティティで設定します。Step bundlesは任意のWorkflowに挿入できます。ユーティリティWorkflowsやWorkflowチェイニングとは異なり、Step BundlesはWorkflow内の任意の場所に配置できます。

ビルドを実行すると、バンドル内の各Stepは、バンドルが挿入された位置で実行されます。

Step bundleを作成するClick to copy link

Workflow Editor
Configuration YAML

Workflow Editorを開きます。
左側でStep bundlesを選択します。
バンドルがない場合はCreate Step bundleをクリックします。

すでにStep bundleが1つ以上ある場合は、中央のドロップダウンメニューを開き、Create Step bundleをクリックします。
ダイアログでバンドルのIDを入力します。
既存のStep bundlesがある場合は、ドロップダウンメニューから選択できます。新しいStep bundleは既存のもののコピーになります。
完了したらCreate Step bundleをクリックします。
Add Step or Step bundleをクリックして、最初のStepを追加します。

あるStep bundleの中にStep bundleを追加することをネスト(入れ子)と呼びます:ネストされたStep bundlesを参照してください。
すでに追加されているStepまたはバンドルの上または下にカーソルを合わせ、プラス記号をクリックして、Stepsやバンドルを追加します。
+ Add inputをクリックして、Configurationタブで新しいバンドル入力を設定します。Newバンドル入力ダイアログでは、バンドル内の複数のStepsを管理する入力変数を定義できます。それらのキーをSteps内で参照し、Workflowごとにカスタム値を割り当てます。

プロジェクトの設定YAMLを開きます。
YAMLファイルのトップレベルにstep_bundlesエンティティを追加し、名前を付けます。このバンドルはこの名前で参照します。
```
format_version: 11
step_bundles:
  install_deps:
```
バンドルの下にstepsプロパティを追加し、実行したいStepsを追加します。ここではWorkflowと同じ方法でStepsを参照できます。

この例では、restore-cache Stepとnpm Stepを追加します。
```
format_version: 11
step_bundles:
  install_deps:
    steps:
    - restore-cache@1: {}
    - npm@1: {}
```

既存のWorkflowにStep bundleを追加します。構文は次のようになります:bundle::<bundle-name>。

workflows:
  ci:
    steps:
    - [email protected]: {}
    - bundle::install_deps: {}
    - deploy-to-bitrise-io@2: {}

ユーティリティWorkflowをもとにStep bundleを作成するClick to copy link

ユーティリティWorkflowをもとにStep bundleを作成できます。このバンドルには、そのユーティリティWorkflowに含まれていたすべてのStepsが含まれます。ただし、ユーティリティWorkflowとは異なり、Step bundleは別のWorkflow内の任意の場所に配置できます。

Workflow Editorを開きます。
左側でStep bundlesを選択します。
Based onドロップダウンメニューから、ユーティリティWorkflowを選択します。
Create Step bundleをクリックします。

Step bundleインスタンスに名前を付けるClick to copy link

Step bundleインスタンスにオプションのメタデータフィールドを追加すると、Workflows内でWorkflowの設定やビルドログを読みやすくできます。

Step bundleインスタンス

Step bundlesは再利用可能な設定ブロックです。一度定義すれば、Workflows間や同じWorkflow内で使い回す(インスタンス化する)ことができます。

Step bundleでは、title、summary、descriptionという3つのオプションのメタデータフィールドを設定できます。これらの属性は、その特定のインスタンスに限り、バンドルの定義から得られる汎用的な情報を上書きし、特定のWorkflowでの表示方法をきめ細かく制御できます。これらの属性を使用すれば、2つのインスタンスを区別するためにStep bundlesにコメントを追加する必要はありません。

Step bundleインスタンスには、次を含めることができます。

title: この特定の用途を表す、人が読みやすい名前。
summary: 簡単な説明。
description: このインスタンスが行うことについての詳細な情報。

これらのフィールドはBitriseUIやビルドログに表示され、各インスタンスが何をしているのかが一目でわかるようになります。

- step-bundle-id:
    title: "A clear, human-readable title for this instance"
    summary: "A short summary of what this instance does."
    description: "A more detailed markdown-supported description if needed."
    inputs:
      - ...

Step bundleインスタンスの追加属性

特定のスキームをビルドおよびテストする、ID run-my-testsで定義されたStep bundleがあるとします。これをメインのWorkflow内で2回使用したいとします。1回目はiPhoneシミュレーターでのユニットテスト用、2回目はiPadシミュレーターでのUIテスト用です。

workflows:
  primary:
    steps:
    - run-my-tests:
        title: "Run unit tests on iPhone"
        summary: Runs the UnitTests test plan.
        inputs:
        - scheme: "MyApp"
        - destination: "platform=iOS Simulator,name=iPhone 14"
        - test_plan: "UnitTests"
    - run-my-tests:
        title: "Run UI tests on iPad"
        summary: Runs the UITests test plan.
        inputs:
        - scheme: "MyApp"
        - destination: "platform=iOS Simulator,name=iPad Pro (12.9-inch)"
        - test_plan: "UITests"

これで、ビルドログとWorkflow editorには、Stepのタイトルとして"Run unit tests on iPhone"と"Run UI tests on iPad"が表示されます。UIテストが失敗した場合、ログを調べなくてもすぐにわかります。

ネストされたStep bundlesClick to copy link

Step bundlesはネストが可能です。つまり、あるStep bundleの中に別のStep bundleを追加できます。これにより、部品を簡単に交換できる大規模で複雑な設定を作成できます。Step bundlesの中には、好きなだけStep bundlesを追加できます。

Workflow Editor
Configuration YAML

Workflow Editorを開きます。
左側でStep bundlesを選択します。
中央のドロップダウンメニューからStep bundleを選択します。
空のバンドルの場合は、Add Step or Step bundleをクリックします。

バンドルにすでにStepsが含まれている場合は、Stepsの間にカーソルを合わせ、プラス記号をクリックします。
ダイアログでStep bundleタブに移動します。
バンドルを選択して、元のバンドルに追加します。
ドラッグアンドドロップでバンドル内を移動します。
完了したらSave changesをクリックします

設定YAMLファイルで、ネストしたいStep bundleをstep_bundlesプロパティ内に定義します。
```
step_bundles:
  initialize:
    steps:
      - activate-ssh-key: {}
      - git-clone: {}
```

bundlesプロパティを使用して、このバンドルを別のバンドルの中にネストします。

step_bundles:
  initialize:
    steps:
      - activate-ssh-key: {}
      - git-clone: {}
  deploy_bundle:
    steps:
      - bundle::initialize: {}
      - deploy-to-bitrise-io: {}

Step bundleの入力Click to copy link

Step bundleでは、inputsキーの下に入力のリストを定義できます。これらはStep bundleに設定できる唯一の入力であり、バンドルの定義の外で追加の入力を定義することはできません。

ただし、Step bundleの事前定義された入力の値は、バンドルの定義の外で設定できます:Step bundleの入力を設定する。

Step bundleの入力はStep inputsと同じモデルを共有します。Step inputsとそのフォーマットについて詳しくは、Step inputsリファレンスを参照してください。

設定YAMLファイルで、Step bundleにinputsプロパティを追加します。
```
format_version: 11
step_bundles:
  install_deps:
    inputs:
```

inputsの下に、Step inputsで使用するキーと値のペアを追加します。

format_version: 11
step_bundles:
  install_deps:
    inputs:     
    - cache_key: "npm-cache-{{ checksum "package-lock.json" }}"
    - npm_command: install

適切なStep inputsにキーを追加します。

この例では、restore-cacheStepのkey入力と、npmStepのcommand入力に対してデフォルト値を設定しました。

format_version: 11
step_bundles:
  install_deps:
    inputs:     
    - cache_key: "npm-cache-{{ checksum "package-lock.json" }}"
    - npm_command: install
    steps:
    - restore-cache@1:
        inputs:
        - key: $cache_key
    - npm@1: {}
        inputs: 
        - command: $npm_command

Step bundleの入力を設定するClick to copy link

Step bundleの入力はStep bundleの定義内で定義するもので、定義の外にnew inputsを追加することはできません。

WorkflowのStepリストにあるStep bundleで定義されたStep bundleの入力には、新しい値を設定できます:

設定YAMLファイルで、Workflowと、そのstepsリスト内のStep bundleを見つけます。

Step bundleが参照されている箇所にinputsプロパティを追加し、キーと値のペアを追加します。

この例では、Step bundleで定義されたdefault valueの代わりに、cache_key入力の新しい値を設定しています。Workflowが実行されると、restore-cacheStepはnpm-cache-{{ checksum "package-lock.json" }}の代わりにnpm-cacheの値を使用します。

format_version: 11
step_bundles:
  install_deps:
    inputs:     
    - cache_key: "npm-cache-{{ checksum "package-lock.json" }}"
    - npm_command: install
    steps:
    - restore-cache@1:
        inputs:
        - key: $cache_key
    - npm@1:
        inputs: 
        - command: $npm_command
workflows:
  ci:
    steps:
    - git-clone@8: {}
    - bundle::install_deps:
        inputs:
        - cache_key: "npm-cache"
    - deploy-to-bitrise-io@2: {}

Step bundleの出力Click to copy link

Stepsは出力変数を生成できます。StepsがStep bundleに含まれている場合、その出力変数はStep bundle以降のWorkflow内のすべてのStepsで利用できます。

たとえば、Workflowで使用されているStep bundleがxcode-archiveStepを使用している場合、バンドルの後の次のStepsは、Stepによって公開されるBITRISE_IPA_PATH出力変数にアクセスできます。

run_ifを使用したStep Bundleの条件付き実行Click to copy link

Step bundlesでrun_if条件を使用すると、Environment Variablesやその他の条件に基づいてバンドル全体を条件付きで実行できます。Workflow内のStep bundle呼び出しにrun_ifを直接適用すると、バンドルが実行される前にその条件が評価されます。評価結果がfalseの場合、バンドル全体とそのすべてのStepsはスキップされます。

run_ifの構文は、個々のStepsと同じように機能します。getenv、enveq、envcontainなど、すべてのrun_ifテンプレート式とカスタムテンプレート関数は、Stepsでもサポートされています。

ドラフトPRに対するSkipデプロイバンドル

この例では、PRがドラフトPRでない場合にのみdeploy-to-stagingバンドルが実行されます。同様に、notify-slackバンドルはビルドが成功した場合にのみ実行されます。

workflows:
  deploy:
    steps:
      - bundle::build-and-test: {}
      - bundle::deploy-to-staging:
          run_if: '{{ not (envcontain "BITRISE_GIT_MESSAGE" "[draft]") }}'
      - bundle::notify-slack:
          run_if: '{{ not .IsBuildFailed }}'

プロジェクトのWorkflow Editorを開きます。
左側のStep bundlesをクリックします。
Configurationタブを選択し、Additional run conditionsの下に値を入力します。

run_ifは、定義でもStep bundleのインスタンスでも指定できます:

run_ifが定義にある場合、それがすべてのインスタンスのデフォルトのrun_ifとして機能します。
run_ifがインスタンスにある場合、それが定義を上書きし、そのインスタンスのみがrun_ifを持つことになります。

Step bundleが通常は条件付きで実行される場合は、定義でrun_ifを定義しておくとよいでしょう。そうすれば、すべてのインスタンスに適切なデフォルトのrun_ifが設定されます。たとえば、リポジトリのクローンとセットアップを行うバンドルは、通常CI環境でのみ意味を持ちます(そのため、git-clone Step自体にrun_if: .IsCIがあります)。

run_if式を使用してStepを有効/無効にし、条件を設定する方法について詳しくはこちらを参照してください。

移行Click to copy link

バンドル内の複数のStepsに同一のrun_if条件を設定している場合、Step bundlesにrun_ifを使用してWorkflowを効率化する方法を紹介します。

変更前:

workflows:
  test:
    steps:
      - bundle::my-test-suite: {}
step_bundles:
  my-test-suite:
    steps:
      - script:
          run_if: '{{ enveq "RUN_TESTS" "true" }}'
          # ...
      - gradle-runner:
          run_if: '{{ enveq "RUN_TESTS" "true" }}'
          # ...
      - deploy-to-bitrise-io:
          run_if: '{{ enveq "RUN_TESTS" "true" }}'
          # ...

変更後:

workflows:
  test:
    steps:
      - bundle::my-test-suite:
          run_if: '{{ enveq "RUN_TESTS" "true" }}'
step_bundles:
  my-test-suite:
    steps:
      - script:
          # ...
      - gradle-runner:
          # ...
      - deploy-to-bitrise-io:
          # ...

Step bundleを作成するClick to copy link​

ユーティリティWorkflowをもとにStep bundleを作成するClick to copy link​

Step bundleインスタンスに名前を付けるClick to copy link​

ネストされたStep bundlesClick to copy link​

Step bundleの入力Click to copy link​

Step bundleの入力を設定するClick to copy link​

Step bundleの出力Click to copy link​

run_ifを使用したStep Bundleの条件付き実行Click to copy link​

移行Click to copy link​

関連情報