🪪 Name your step bundle instances for better clarity

[kaushal.bitrise]

You can now add optional metadata fields to step bundle instances to make your workflow configs and build logs easier to read.

What’s new

We’ve added three new optional attributes – title, summary, and description – that you can set for any step bundle instance within your workflow. These attributes override the generic information from the bundle’s definition for that specific instance only, giving you granular control over how it’s displayed.

Each instance can now include:

• title: a human-readable name for this specific usage
• summary: a brief description
• description: detailed information about what this instance does

These fields show up in the Bitrise UI and build logs, making it immediately clear what each instance is doing.

- 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:
      - ...

What problem this solves

Step bundles are reusable config blocks – you define them once, then use them (instantiate them) across multiple workflows or multiple times in the same workflow. Until now, when you had multiple instances of the same step bundle, they all looked identical in your config and build logs. If you’re using the same step bundle for different purposes (like running tests for iOS and Android separately, or deploying to staging vs production), both instances would appear with the same generic name, forcing you to dig into the step’s logs to understand which one failed or what its specific purpose was.

There is a better way.

A quick refresher: definition vs. instance

Step bundles have two parts:

• Definition: This is where you declare your step bundle and assign it a unique ID (e.g., run-ios-tests) and an optional title (a human-readable name that also appears in the step bundle library). You define it once in the step_bundles section of your bitrise.yml.
• Instance: This refers to any place where you use that bundle in a workflow by referencing its ID. You can have many instances of a single definition.

Example

Let’s say you have a step bundle defined with the ID run-my-tests that builds and tests a specific scheme. You want to use it twice in your primary workflow: once for unit tests on an iPhone simulator, and again for UI tests on an iPad simulator.

Before, comments were the only way to distinguish the two instances. Now, you can add a title to each instance to make it perfectly clear:

workflows:
  primary:
    steps:
    - step-bundle-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"

    - step-bundle-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"

With this change, the build log and workflow editor will now display “Run unit tests on iPhone” and “Run UI tests on iPad” as the step titles. If the UI tests fail, you’ll know immediately without having to inspect the logs.

Happy building