A workflow is a collection of steps, environment variables, and other configurations for a single
Defining a workflow ⚓
The only requirement for a workflow is an ID. As an example, in this configuration we declared one workflow with the ID
format_version: 1.3.1 workflows: test:
You can define multiple workflows and run a specific workflow with
bitrise run WORKFLOWID. Below configuration contains two workflows,
second, so you can execute both
bitrise run first and
bitrise run second.
format_version: 1.3.1 workflows: first: second:
Adding Steps to a workflow ⚓
To add Steps to a workflow simply include
steps: and then add the Step(s).
For example, here is how to run two script Steps after each other:
format_version: 1.3.1 default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git workflows: test: steps: - script: title: First step - script: title: Second step
When you run
bitrise run test, the Bitrise CLI will run the two script Steps one by one, starting with the
First step and then continuing with the
Defining workflow specific parameters / environment variables ⚓
Besides Steps you can also specify environment variables for every workflow.
A workflow’s environment variables are used when the workflow is executed, and are available for every step in the workflow.
Here is an example for defining two environment variables (
ENV_VAR_TWO) in the
format_version: 1.3.1 default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git workflows: test: envs: - ENV_VAR_ONE: first value - ENV_VAR_TWO: second value
Chaining workflows and reusing workflows ⚓
You can chain workflows to run one/multiple workflows(s) before and/or after a specific workflow.
Example workflow for chaining five workflows:
format_version: 1.3.1 default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git workflows: send-notifications: steps: # send notifications setup: steps: # setup steps to run test: before_run: - setup envs: - IS_TEST: "true" steps: # test steps to run ci: before_run: - test after_run: - send-notifications deploy: before_run: - test steps: # steps to deploy after_run: - send-notifications
Based on the above example, if you run:
bitrise run send-notifications: only the Steps of the
send-notificationsworkflow will be executed
bitrise run setup: only the Steps of the
setupworkflow will be executed
bitrise run test: first the Steps of the
setupworkflow will be executed, then the Steps declared in
bitrise run ci: will execute the Steps of the workflows in the following order:
ciworkflow doesn’t have any Steps, but that’s not an issue. It just means that no step will be executed here and the build will continue with the next workflow in the chain.)
bitrise run deploy: will execute the Steps of the workflows in the following order:
This means that you can define what a
test should do in your project in the
test workflows only once, and then you can reuse those in other workflows. There’s no need to duplicate Steps between workflows.
To sum it up, when you chain workflows, it’s the same as if you’d create one workflow which would include all Steps from all the workflows chained after each other. So, for example, one Step’s outputs will be available for every other Step which is executed after that Step during the build, (regardless of whether the other Step is in the same or in another workflow). If a Step is executed after another Step during the build, it can access the outputs of the previous Steps.
About workflow environment variables ⚓
Workflow specific environment variables are made accessible when the workflow is executed. These environment variables are available for workflows executed after that workflow, but not in the ones executed before that workflow.
For example, if you
bitrise run ci, the
IS_TEST environment variable won’t be available in the
setup workflow, as that runs before the
IS_TEST will be available for the steps in
This is true even if the workflow doesn’t have any Steps. This can be utilized if you want to create generic workflows, which can do different things based on environment variables, and you specify those environment variables through a “wrapper” workflow.
format_version: 1.3.1 default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git workflows: generic-build: steps: # steps which depend on `BUILD_TYPE` environment variable build-alpha: envs: - BUILD_TYPE: alpha after_run: - generic-build build-beta: envs: - BUILD_TYPE: beta after_run: - generic-build
As you can see in the above example, neither
build-beta workflows have any steps. Instead the Steps are defined in
generic-build, but when you
bitrise run build-alpha the
BUILD_TYPE environment variable will be set to
alpha, while if you
bitrise run build-beta, the
BUILD_TYPE environment variable will be set to
As discussed above, workflow defined environment variables are only available in the workflow it defines, and in the ones executed after that workflow. So in our example,
generic-build is included as
after_run workflow, therefore, the
BUILD_TYPE environment variable will be available in the steps of
generic-build. But if you’d use
before_run instead of
after_run, that would mean that technically the steps of
generic-build are processed and executed before processing the
build-beta workflows, so the
BUILD_TYPE environment variable would not be available in the step of
Utility workflows ⚓
Utility workflows help you organize your workflows more efficiently.
If you chain workflows together, you might quickly end up with tons of small, reusable workflows. Finding the right workflow might get a bit tricky. Utility workflows to the rescue! The Bitrise CLI supports a small notation, called utility workflow: a workflow whose ID starts with an underscore character, for example,
You can find utility workflows at the end of the workflow list if you run
bitrise run or
bitrise workflows. Mind you, utility workflows can’t be executed directly with a
bitrise run command. These workflows can be referenced in
Using the above example with five workflows (
test), if you run
bitrise run in the directory of the
bitrise.yml without specifying a workflow, you’ll get list of all five workflows:
The following workflows are available: * ci * deploy * send-notifications * setup * test You can run a selected workflow with: $ bitrise run WORKFLOW-ID
You most likely don’t want to run
send-notifications by itself, only through
deploy. If you prefix those with an underscore character to make them utility workflows, the
bitrise run output will better highlight which workflows are meant to be executed directly:
The following workflows are available: * ci * deploy You can run a selected workflow with: $ bitrise run WORKFLOW-ID The following utility workflows are defined: * _send-notifications * _setup * _test Note about utility workflows: Utility workflow names start with '_' (example: _my_utility_workflow). These workflows can't be triggered directly, but can be used by other workflows in the before_run and after_run lists.