Skip to main content

Step bundles

Abstract

Step bundles allow you to reuse Steps and sequences of Steps in any Workflow in a convenient way, without having to manually copy and paste Steps from a YAML file.

Step bundles allow you to group multiple steps into a single unit. With Step bundles, you can reuse Steps and sequences of Steps without manually copying and pasting from a YAML file.

Step bundles are configured with a root level entity called step_bundles. You can insert Step bundles into any Workflow. Unlike utility Workflows and Workflow chaining, Step Bundles can be placed anywhere in a Workflow.

When running a build, each Step within the bundle will run at the position the bundle is inserted.

Creating a Step bundle

You can only create Step bundles in a configuration YAML file. The bundle will be visible on the Workflow Editor but you can't create it on the graphical UI.

  1. Open the configuration YAML of your project.

  2. Add a step_bundles entity to the top level of the YAML file and give it a name. You will refer to the bundle by this name.

    format_version: 11
step_bundles:
  install_deps:

  3. Add a steps property under your bundle and add the Steps you want to run. You can reference Steps here the same way as in a Workflow.

    In this example, we add the restore-cache Step and an npm Step.

    format_version: 11
step_bundles:
  install_deps:
    steps:
    - restore-cache@1: {}
    - npm@1: {}

  4. Add your Step bundle to an existing Workflow. The syntax works like this: bundle::<bundle-name>.

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

Configuring default inputs and common values for Steps in a bundle

In any Step bundle, a list of Environment Variables can be defined under the envs key. You can use these variables to predefine the inputs of Steps included in the bundle, or share common values among the Steps.

The variables will be available among the Step bundle's included steps, but not outside of the Step bundle. For example, they can be used to preconfigure Step inputs within the Step bundle.

  1. In your configuration YAML file, add the envs property to your Step bundle.

    format_version: 11
step_bundles:
  install_deps:
    envs:

  2. Under envs, add key-value pairs that will be used for Step inputs.

    format_version: 11
step_bundles:
  install_deps:
    envs:     
    - CACHE_KEY: "npm-cache-{{ checksum "package-lock.json" }}"
    - NPM_COMMAND: install

  3. Add the keys to the appropriate Step inputs.

    In our example, we configured default inputs for the key input of the restore-cache Step and the command input of the npm Step.

    format_version: 11
step_bundles:
  install_deps:
    envs:     
    - 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

Overriding Step bundle variables

You can override any Environment Variables defined in the Step bundle by reassigning them in the Step list of the Workflow:

  1. In your configuration YAML file, find your Workflow and the Step bundle in its steps list.

  2. Add an envs property where your Step bundle is referenced, and add a key-value pair to it.

    In this example, we override the value of the CACHE_KEY variable. When the Workflow runs, the restore-cache Step will use the npm-cache value instead of npm-cache-{{ checksum "package-lock.json" }}.

    format_version: 11
step_bundles:
  install_deps:
    envs:     
    - 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:
        envs:
        - CACHE_KEY: "npm-cache-"
    - deploy-to-bitrise-io@2: {}

Step bundle outputs

Steps can generate output variables. When Steps are included in a Step bundle, their output variables are available to all Steps in the Workflow after the Step bundle.

For example, if the Step bundle used in the Workflow uses the xcode-archive Step, the next Steps after the bundle will have access to the BITRISE_IPA_PATH output variable which is exposed by the Step.

In this section: