Skip to main content

Step inputs reference

Abstract

Step inputs are environment items that tell the Bitrise CLI how to run a given Step. The inputs of a Step are defined in the step.yml file of every Step by setting the inputs property..

Step inputs are environment items that tell the Bitrise CLI how to run a given Step. The inputs of a Step are defined in the step.yml file of every Step by setting the inputs property..

Step inputs have the same syntax as every environment property. It consists of two main parts: a KEY: value pair and an opts field.

inputs:
- my_key_for_the_env: "default value" 
  opts: 
    title: An example env var item 
    is_dont_change_value: false 
    category: example
  • my_key_for_the_env: the key of the input (required).

  • default value: the default value of the input. You don’t always have to provide a default value.

  • opts: optional properties.

Step input properties

The available properties for Step inputs:

  • title, summary and description : metadata, for comments, tools and GUI.

    Meta properties as permanent comments

    These meta properties can be used for permanent comments. Standard YML comments are not preserved when the YML is normalized, converted to JSON or otherwise generated or transformed. These meta properties are.

  • is_expand : can be set to true or false. The default value is true so the Bitrise CLI expands Environment Variables (Env Vars) before passing it on to the Step. That means that if a Step input's value is an Env Var, the Bitrise CLI will pass the variable's value to the Step. If set to false, the CLI will pass the Env Var's key as a string.

  • skip_if_empty : can be set to true or false. If set to true, the input will not be used if its value is empty.

  • category : used to categorize the input. Inputs with the same category will appear grouped under one menu on the website UI, for the sake of convenience.

  • value_options : list of the available values.

  • is_required : can be set to true or false. If set to true, the step requires a non-empty value to be set for the input.

  • is_dont_change_value : can be set to true or false. If set to true, the value of the input should not be changed and/or should be hidden on UIs. Mainly used for debug inputs and for “connection” inputs (set to outputs of other Steps, to connect this Step with another one).

  • is_template : can be set to true or false. If set to true

    ,

    the input’s value will be evaulated as a Go template.

  • is_sensitive: marking an input as sensitive means that it will only accept a Secret Environment Variable as its value. It is most frequently used for sensitive information such as passwords, API keys, tokens, but any input can be marked sensitive.

Using template expressions for Step inputs

If you need a Step to use a certain value only in certain circumstances, use template expressions as Step inputs. Template expressions are evaluated before the Step uses the input. They are written in Go’s template language.

Set the is_template property in the step.yml file of your project to use template expressions.

  1. Open the step.yml file of your project.

  2. Find the Step in which you wish to use a template expression.

  3. Add an opts field to the content of the Step.

  4. Add the is_template property to opts and set its value to true.

  5. Add the template expression to the Step’s content.

Example 1. Checking if the Bitrise CLI is in CI mode
- script:
  title: Template example
  inputs:
  - content: |-
      {{if .IsCI}}
      echo "CI mode"
      {{else}}
      echo "not CI mode"
      {{end}}
    opts:
      is_template: true