Step inputs are environment items that tell the Bitrise CLI how to run a given Step. As discussed in the Steps section, the default inputs can be found in the step.yml file of every step and the user only needs to manually set the inputs they wish to change.
Step inputs can be defined in the step.yml file of the project by setting the inputs property. They have the same syntax as every environment property. It consists of two main parts: a KEY: value pair and an opts field.
- 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 environment item (required).my value for the env: the default value of the input. You don’t always have to provide a default value.opts: optional properties.
Of course, a step input can have many more properties - let’s take a look at them!
title,summaryanddescription: metadata, for comments, tools and GUI. Note: 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 totrueorfalse. If set totrue, the shell environment variables are expanded/resolved.skip_if_empty: can be set totrueorfalse. If set totrue, the input will not be used if its value is empty.category: used to categorize the input. Inputs with the samecategorywill 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 totrueorfalse. If set totrue, the step requires a non-empty value to be set for the input.is_dont_change_value: can be set totrueorfalse. If set totrue, 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 totrueorfalse. If set totrue,the input’s value will be evaulated as a Go template.
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 - you can read more about that here.
Set the is_template property in the step.yml file of your project to use template expressions.
- Open the
step.ymlfile of your project. - Find the step in which you wish to use a template expression.
- Add an
optsfield to thecontentof the step. - Add the
is_templateproperty tooptsand set its value totrue. - Add the template expression to the step’s
content.
Example:
- script:
title: Template example
inputs:
- content: |-
echo "CI mode"
echo "not CI mode"
opts:
is_template: true
Check out the template utility on GitHub!