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:
-
The StepLib source: a library of Step repositories, such as the official Bitrise Step Library.
-
The Step ID: every Step must have an ID as part of its
step.yml
definition. -
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::[email protected]:
-
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/[email protected]:
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/[email protected]:
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.