Step reference/ID format

A Step reference can contain three components:

  1. The StepLib source

  2. The Step ID

  3. The Step version

Use the following syntax to reference a Step:

<step_lib_source>::<step-id>@<version>:

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

- script: 

This could be written as:

https://github.com/bitrise-io/bitrise-steplib.git::script@1.1.3:
  • 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: https://github.com/bitrise-io/steps-script. 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::https://github.com/bitrise-io/steps-script.git@1.1.3:

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::https://github.com/bitrise-io/steps-script.git@soon-to-be-released:

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.