Skip to main content

Step reference/ID format


To refer to a Step in a bitrise.yml file, you need to include at least the Step ID. Optionally, you can specify the StepLib source and the Step version, too.

A Step reference can contain three components:

  1. The StepLib source: a library of Step repositories, such as the official Bitrise Step Library.

  2. The Step ID: every Step must have an ID as part of its step.yml definition.

  3. The Step version: the numerical version of the Step you want to include.

Use the following syntax to reference a Step:


From these three components only the Step ID is required. For example:

- script: 

This could be written as:
  • If the version is not defined, the latest version of the step will be used.

  • If the StepLib source is not defined, the default_step_lib_source will be used.

We recommend using the specific version of a Step, for example, 1.1.3.

Special Step sources

There are two special Step sources:

  • git::

  • and path::

When you use one of these sources, the Step won’t be identified through a Step Library but through the ID data you specify.

The git:: source

The git:: source is the repository of the Step on your git hosting provider. The script Step’s GitHub source is: To reference the script Step directly through a git reference, you can use the git:: source, the Step’s git clone URL, and the branch or tag in the repository.

To reference the 1.1.3 version tag of the script Step’s repository:

- git::

In general, whenever you can use a Step version through a Step Library, you should do that, instead of using the git:: source type. Features like local step caching, network caching, or alternative download URLs are only supported for Steps shared in a StepLib.

But this type of referencing allows certain things you can’t get through a StepLib. For example, the git:: source type can be used for not-yet-published or work-in-progress states of a Step. If you develop your own Step, you can use this git:: source type to test your step before you publish it in a StepLib.

To reference soon-to-be-released branch of your repository where you're developing a Step:

- git::

The path:: source

The path:: source specifies a local path to a Step's repository, and it requires no version information. Both absolute and relative local paths are supported. A relative path is relative to the folder containing the bitrise.yml file.

- path::/path/to/my/step:

- path::./relative/path:

This is useful for Step development. It can also be used if you want to include your build Steps in your app’s source code.