Developing a new Step

The title property sets the name of the Step, as it will appear on bitrise.io. It should be short and descriptive. Include the name of the service and the function it fulfils, such as Git Clone. Here’s a few guidelines for your Step titles:

A single line of the most significant information about the Step. It can’t be longer than a 100 characters.

The summary is visible by default on the Workflow Editor. If a user expands the summary, the Step’s description will be presented - if there is one, of course.

A detailed explanation of the Step. It should include:

By default, the Step’s description is collapsed on the Workflow Editor and the summary is presented.

The available platform types are controlled by the project_type_tags attribute. If your Step is available for every platform or project type, do not specify project_type_tags. In any other case, select all platform types for which your Step is available.

The available values are:

Functional categories are controlled by the type_tags attribute in the step.yml. One Step should have only a single type tag assigned to it. Use utility only if you believe none of the other types fit your Step.

The available values are:

Use lower case snake case style input keys. For example, project_path.

There is no need to add domain-specific prefixes to the input keys, as inputs are only exposed for the Step run process. This means project_path input will not overlap with subsequent Steps’ project_path inputs.

Step input values are strings: the Bitrise CLI exposes the Step inputs as Environment Variables to the Steps.

Provide default values for Step inputs if possible (and if it makes sense). That makes the Step configuration easier for Bitrise users.

Environment Variables must not be used as default values, unless:

This is because the Workflow Editor highlights required inputs without values to express the Step will not work without setting a valid value for the given input. If you set an Env Var, which does not have an automatically assigned value, as the default value for an input, the Workflow Editor will think the required input in question has a valid value set (even if the default Env Var has no value yet).

Also, there is no reason to suggest a certain name for an Environment Variable this way: users might have the same value assigned to an Env Var with a different name.

Let’s talk about how Step inputs are passed to code and how they are presented.

A Step input can have a name, a summary, and a description, just like the Step itself. To define these:

Let’s take a look at how these should look like!

Here is an example:

- install_defaults: "yes"
  opts:
    description: Installs default (Bitrise) Wildcard Provisioning Profile and
      Certificate files for testing.
    summary: Installs default (Bitrise) Wildcard code signing files.
    title: Installs default code signing files

Now, let’s talk about some other configuration options for Steps.

Required inputs must have a valid value, otherwise the Step will fail.

To mark a Step input as required, use the is_required option of the opts property. It has two values: true and false. If set to true, the input will be displayed as REQUIRED on the Workflow Editor.

- keychain_password: $BITRISE_KEYCHAIN_PASSWORD
  opts:
    title: "Keychain's password"
    is_required: true

You can mark Step inputs as sensitive to make sure their values do not get exposed. Sensitive inputs only accept Secrets as values. This ensures they are not visible in build logs.

To mark a Step input as sensitive, use the is_sensitive option of the opts property. It has two values: true and false. If set to true, the input will be displayed as SENSITIVE on the Workflow Editor.

inputs:
  - certificate_urls: $BITRISE_CERTIFICATE_URL
    opts:
      title: "Certificate URL"
      is_sensitive: true

As noted earlier, it is possible to use Environment Variables as the value of any given input. By default, the Step will expand the Env Var and pass its value to the Step execution. This is defined by the is_expand option of the opts property.

- project_path: $BITRISE_PROJECT_PATH
  opts:
    is_expand: true

The is_expand option can have two values: true or false. If set to true - this is the default behavior -, the value of $BITRISE_PROJECT_PATH will be passed to Step execution. If set to false, the string $BITRISE_PROJECT_PATH will be passed (and this particular Step will fail as it will not find the project location).

The category option is used to group inputs together. Inputs belonging to the same category are displayed together and collapsed by default in the Workflow Editor.

- default_certificate_passphrase: $BITRISE_DEFAULT_CERTIFICATE_PASSPHRASE
  opts:
    category: Default code signing files
    description: |
      Certificate passphrase of the default certificate.
    is_sensitive: true
    title: Default certificate passphrase

In this case, this input will appear with all the other inputs that have the same category set.

Categories may be used if the Step has more than six inputs. The suggested maximum number of inputs in a group or in the root is six.

Please keep in mind, when designing Step categories, that:

It is absolutely possible to accept a list of values for a given input. If you wish to do so, we strongly recommend adding a list suffix to the key of the input (for example, input_path_list), and expect the values to be provided as a newline character (\n) separated list (for example, first value\nsecond value).

Please use this solution unless you really need to use another character for separating values. Based on our experience, the newline character (\n) works really well as a universal separator character, as it’s quite rare in input values (compared to ,, ;, = or other more common separator characters).

As a best practice, you should filter out empty items. Use either:

first value\n\nsecond value

or

first value\n       \nsecond value

For output keys, use upper case snake case style output keys, for example: OUTPUT_PATH.

Step outputs are always exported as Environment Variables (Env Var). For example, the Xcode Archive & Export for iOS Step generates an IPA file: this output is exported as the BITRISE_IPA_PATH Env Var:

outputs:
- BITRISE_IPA_PATH:  
  opts:    
    title: .ipa file path   
    summary: Local path of the created .ipa file

As the example shows, the output definition contains a key (BITRISE_IPA_PATH) and under the opts property, it also includes a title and a summary. In the Workflow Editor, the key and the title are visible by default: these are required. In addition, you can add a summary and a description:

It is absolutely possible to provide a list of values for a given output. If you wish to do so, we strongly recommend adding a LIST suffix to the key of the output (for example, BITRISE_APK_PATH_LIST), and expect the values to be provided as a newline character (\n) separated list (for example, first value\nsecond value).

Please use this solution unless you really need to use another character for separating values. Based on our experience, the newline character (\n) works really well as a universal separator character, as it’s quite rare in input values (compared to ,, ;, = or other more common separator characters).

If you need to keep a binary, assets or anything else required for your Step that should be bundled in the Step repository, then you can include them beside your step.yml file and the code of your Step. The Bitrise CLI automatically exports an Environment Variable called BITRISE_STEP_SOURCE_DIR that allows you to access these files at any time.

For example, you can access a .jar file in the root of your Step’s repository like this:

$BITRISE_STEP_SOURCE_DIR/mytool.jar