Intro

Bitrise is a collection of tools and services to help you with the development
and automation of your software projects, with a main focus on mobile apps.

Most of this DevCenter describes things related to bitrise.io,
the hosted automation service, but the heart of Bitrise is the
open source Bitrise CLI / runner,
which is responsible for interpreting the build configuration and executing it.

This open source runner is referred to as Bitrise CLI or Bitrise,
and it's a tool which you can install and run on your own Mac/PC!

This section of the DevCenter is dedicated to this runner (Bitrise CLI) and the
bitrise.yml configuration format, the things described here don't even require a
bitrise.io account, the only requirement is that
you install the Bitrise CLI on your Mac/PC.

Bitrise CLI on bitrise.io

The CLI you can install is exactly the same as what's used on bitrise.io.
When a build starts on bitrise.io, a virtual machine
is created for the build with the Bitrise CLI preinstalled,
and once the virtual machine is ready, the build is performed through the Bitrise CLI.

To run a Bitrise build on your machine, you can install our open source runner
and use the bitrise command to execute your workflows locally.
It's a great help when you're developing steps, debugging builds,
or just want to use Bitrise for any kind of automation on your machine.

The configuration format of the Bitrise CLI is referred to as bitrise.yml,
as that's the expected file name the configuration should be saved with.

Technically the CLI can also accept the configuration in JSON format,
and the file name can be changed too, but if you save the configuration
into a file named bitrise.yml, you can simply bitrise run in that directory,
without specifying any configuration path, and the CLI will read the
configuration from bitrise.yml automatically.

The StepLib is the collection of the build steps you can use in your
bitrise.yml. The steps in the official Bitrise StepLib
are all open source, you can write your own too and then share it with others!
See the step-template for more information.

You can also create your own Step Library if you want to, but it's usually
easier to just reference your steps with their git clone URL directly
if you don't want to share it with others.

Custom StepLib support in tools

The Bitrise CLI tools can work with custom step libraries, but other
tools like the Visual Workflow Editor on bitrise.io
might be limited in functionality for steps not available in the main
Bitrise StepLib.

If possible you should share your steps in the
main Bitrise StepLib,
to help others as well as for the extra reliability the StepLib offers.

Custom StepLibs can also provide fallbacks (alternative download URLs, caches),
automatic and preiodic checks etc. to provide the best reliability, but you get all these for free
if you use the main Bitrise StepLib.

You have a code which can be updated independently from other parts,
and you can re-use/share this between your configurations.

Shared maintenance: when you use Steps created by others you don't have to maintain
the codes, but you can contribute to it if you want to, or create and use your own.

Versioned: If a new version doesn't work for you, you can always go back to a previous one.

We frequently push features as Steps instead of building it into the core tools.
This allows faster and versioned iterations, and updating the parts independently.
We try to maintain compatibility as much as possible, so older versions can work too,
providing a way to upgrade when it's appropriate for you.