Creating your own Step is as simple as running a
bitrise CLI (v1.6.1+) command and following the guide it prints. You can generate Steps using either the Bash or Go toolkits.
If you don’t have the Bitrise CLI installed, check the installation guide here.
Creating the Step ⚓
Once the Bitrise CLI is installed, create your own Step with three simple commands.
# If this is the very first time you use the CLI / if you just installed the CLI run this: bitrise setup # If you want to update the Step plugin to the latest version: bitrise plugin update step # And to generate a new Step, simply run this command and follow the guide it prints: bitrise :step create
bitrise :step without any commands will print the plugin’s help.
Once you are done, you should have a
step.yml and, depending on whether you chose Go or Bash, a
main.go or a
step.sh file in your new Step’s repository.
step.ymlfile is the Step interface definition, containing dependencies, Step inputs and Step outputs as well as other step properties.
step.shcontains the actual functionality of the Step. DO NOT CHANGE the working directory!
The generated Step’s README describes:
- how you can run your Step locally, before you even commit the code,
- how you can test and use your Step in any build by using the
- how you can share your Step with others through the Bitrise StepLib if you wish to do so.
Step development guidelines ⚓
A newly created Step is a ‘skeleton’: in the
step.yml file, certain properties are assigned default values and example inputs and outputs are created to show the structure of these.
Many step properties are automatically generated - for example, when sharing the Step - while other properties should be set manually if they are required. When creating a new Step with the plugin, only the
project_type_tags property does not get filled with some value by default but of course you can manually modify all properties in the
Naming conventions: versioning, Step ID, step inputs and outputs ⚓
- You should use semantic versioning (MAJOR.MINOR.PATCH) for your Step. For example,
- For Step IDs, use hyphens as separator if the ID contains multiple words. For example,
- For inputs, use lower case snake case style input IDs. For example,
- If your step input should accept a list of values, postfix the input ID with
input_path_list). We strongly recommend using the pipe character as a separator (for example,
first value|second value).
- For outputs, use upper case snake case style output IDs. For example,
- If an output should be able to provide a list of values, postfix the input ID with
OUTPUT_PATH_LIST). We strongly recommend using the pipe character as a separator (for example,
first value|second value).
- Filter out empty items! For example,
first value| |second valueshould be treated exactly the same way as
first value|second value.
Environment variables in Steps ⚓
Do not use Environment Variables directly in your Step’s code. Instead, expose every outside variable as an input of your Step and set the default value of that input to the Environment Variable you want to use. You can do this in the
step.yml file. This way it’s easier to test the Step and the user of the Step can easily declare these inputs, without having to scour through code for the required variable.
xcode-archive Step generates an output Environment Variable
$BITRISE_IPA_PATH. Create an input for this in your Step:
inputs: - ipa-path: $BITRISE_IPA_PATH opts: title: "IPA path"
Secret environment variables in Steps ⚓
You can mark Step inputs as Sensitive to make sure their values do not get exposed. Sensitive inputs only accept Secrets - secret environment variables - as values. This ensures they are not visible in build logs.
To mark a Step input as sensitive, use the
is_sensitive property. It has two values:
inputs: - certificate_urls: $BITRISE_CERTIFICATE_URL opts: title: "Certificate URL" is_sensitive: true
Submodules and dependencies ⚓
Do not use submodules, or require any other resource downloaded on-demand in your Step. Try to include everything required for your Step in the Step’s repository. Otherwise you can run into problems if, say, the Step fails to download a resource because of a network error or some authorization problem.
In the case of submodules, you should include the content of the other repository instead of using it as a submodule of your Step’s repository.
You can, however, declare dependencies that you can fetch from an OS dependency manager, such as
brew. For more information on declaring dependencies, see Step properties.
Need some inspiration for a new Step idea? Look no further, we have a list! This way please :)
Sharing a new Step ⚓
If you wish to share your newly created Step with the wider world, that’s great - and simple!
We recommend you start with the command
bitrise share. This will print you a guide on sharing steps - all you need to do is follow! But we’ll summarize the most important things here as well, if you wish to look at the process before even firing up a command line interface.
- Make sure your Step is stored in a public git repository.
- Fork the StepLib repository you want to have your step in. We recommend using the The official Bitrise StepLib!
- Prepare your forked StepLib locally for sharing:
$ bitrise share start -c https://github.com/[your-username]/bitrise-steplib.git
- Add the step version tag to your Step’s repository.
- Add the Step to your forked StepLib repository:
$ bitrise share create --tag [step-version-tag] --git [step-git-uri].git --stepid [step-id]
- Optionally, perform a complete health check on your forked StepLib:
$ bitrise audit -c https://github.com/[your-username]/bitrise-steplib.git
- Create a Pull Request in the original StepLib repository.
And that’s it, you are done! Once your PR is merged, your step will be available to everyone who uses the StepLib repository you chose.
The configuration format of the Bitrise CLI is referred to as bitrise.yml. This is the expected file name the configuration should be saved with.
Any tool that can edit `bitrise.yml` can add custom properties to it. This way you can add special properties or notes to your env vars, or even try new configurations...
The open source Bitrise CLI / runner is responsible for interpreting and executing the build configuration. Using the Bitrise CLI you can run the same configuration on any compatible Mac/PC,...