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

  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: {}

Step bundle inputs

In any Step bundle, a list of inputs can be defined under the inputs key. These are the only inputs you can set for a Step bundle: you can't define additional inputs outside the bundle definition.

You can, however, set values for the predefined inputs of a Step bundle outside the bundle definition: Configuring Step bundle inputs.

Step bundle inputs share the same model as Step inputs. You can read more about Step inputs and their format: Step inputs reference.

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

    format_version: 11
step_bundles:
  install_deps:
    inputs:

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

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

Configuring Step bundle inputs

You define Step bundle inputs in the Step bundle definition and you can't add new inputs outside the definition.

You can set new values for Step bundle inputs defined in the Step bundle 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 inputs property where your Step bundle is referenced, and add a key-value pair to it.

    In this example, we set a new value of the cache_key input instead of its default value defined in the Step bundle. 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:
    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 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: