Creating and sharing your own Step

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.

Use the latest Bitrise CLI!

Make sure you have the latest version of the Bitrise CLI, or at the very least, you have version 1.6.1 or higher. Call bitrise --version to check your Bitrise CLI version. This is important because the CLI uses the :step plugin to create Steps and this plugin was introduced as a core plugin in v1.6.1.

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

Running bitrise :step without any commands will print the plugin’s help.

Once you are done, you should have a step.yml file and, depending on whether you chose Go or Bash, a main.go or a file in your new Step’s repository.

The generated Step’s README describes:

Before proceeding with step configuration

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 step.yml file.

Step inputs and outputs are also Step properties. For more information, see Step properties, Step inputs, Step outputs.

Naming conventions: versioning, Step ID, step inputs and outputs

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.


The xcode-archive Step generates an output Environment Variable $BITRISE_IPA_PATH. Create an input for this in your Step:

  - ipa-path: $BITRISE_IPA_PATH
      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: true and false.

The is_expand property

If you mark an input as sensitive, the is_expand property of the input also must be true (which is the default setting)!

  - certificate_urls: $BITRISE_CERTIFICATE_URL
      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 apt-get or brew. For more information on declaring dependencies, see Step properties.

If you have any questions visit our community discussion site or contact us!

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

  1. Make sure your Step is stored in a public git repository.
  2. Fork the StepLib repository you want to have your step in. We recommend using the The official Bitrise StepLib!
  3. Prepare your forked StepLib locally for sharing:
    $ bitrise share start -c[your-username]/bitrise-steplib.git
  4. Add the step version tag to your Step’s repository.
  5. Add the Step to your forked StepLib repository:
    $ bitrise share create --tag [step-version-tag] --git [step-git-uri].git --stepid [step-id]
  6. Optionally, perform a complete health check on your forked StepLib:
    $ bitrise audit -c[your-username]/bitrise-steplib.git
  7. 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.