# Step reference/ID format

Abstract

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:

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