Use bitrise.yml from repository

Storing the build configuration (bitrise.yml) in your repository can be a great idea.
It has its own PROs and CONs of course, so you have to decide it yourself
whether this solution is a good fit for your project or not.

You can find a discussion about what are the advantages and
disadvantages of this approach on GitHub.
To highlight a few things to keep in mind if you'd want to store and use
the bitrise.yml from your repository:

You can of course store the trigger_map (or Triggers on the web UI)
in your repository (in bitrise.yml), but if you do that you'll lose
the ability to ignore patterns. This is because bitrise.io
have to evaluate the Trigger map before the repository would be cloned
in order to be able to avoid starting a build based on the Trigger map.

The source code is never stored on bitrise.io,
(see Code Security - Source code for more information),
so if you store the trigger map in your repository, the only way to check it
is to clone it first. Even if you prepare your trigger_map in your repository to ignore
patterns, bitrise.io will start a build to clone
the repository, before it could abort it.

In contrast, if you specify the Trigger Map on bitrise.io,
you can ignore patterns in a way that it won't even start a build.

If you use the bitrise.yml from the repository, that means that when you
rebuild a specific commit, it will use the same bitrise.yml every time,
the one stored in the repository for that git commit.

The only way to change the configuration is to checkout the related
branch, change the bitrise.yml, commit the changes,
push and start a new build (rebuild of a commit won't work,
that will always get the same bitrise.yml, the one stored at the commit).

If you store your build configuration on bitrise.io
you can always rebuild any commit with a new build configuration,
the configuration is not tied to the commit / state of the repository.
You can simply change a parameter and hit "rebuild", the new build
will use the latest configuration from bitrise.io.

You can't edit the configuration in the Workflow Editor on bitrise.io⚓

The Workflow Editor on bitrise.io can only be used
to visualize and edit the configuration stored on bitrise.io.

The offline workflow editor
of course can be used, so this is probably not a huge issue - and we're
working on it to make it as streamlined as possible - but might
make it harder to get started (as you have to install the Bitrise CLI
locally).

When someone sends a Pull Request they can modify the bitrise.yml
in your repository any way they like it. A recent trend for example
is to send pull requests which run a bitcoin miner, as long as
that's possible. This can make your builds to queue, until you
abort the related build or it hits the build time limit.

Define a "wrapper" build config on bitrise.io,
which defines how and from where your bitrise.yml will be retrieved.
E.g. you could store the bitrise.yml in a GitHub Gist
too, not just in your repository. In this example we'll use the configuration
from the repository, so the "wrapper" configuration on bitrise.io
will define how the repository should be retrieved. Note: this also allows
more customization, for example if the repository have to be accessed through
a VPN, you can configure that in the "wrapper" config and it will work.

Run the build configuration (bitrise.yml) with the Bitrise CLI.
This is the same runner which runs any other build on the bitrise.io
build virtual machines, so it's always preinstalled and ready to be used.

The example here is really simple to setup, should work in most cases (unless
you need a VPN for cloning the repository for example), but it also requires
you to maintain the Trigger Map on bitrise.io instead
of in the repository, as that is the recommended solution.

Step by step:

Create an app on bitrise.io, or if you already have it registered
open it.

Go to the Workflow tab to open the Workflow Editor.

In the Workflow Editor switch to bitrise.yml mode

In the bitrise.yml mode:

If you already have a configuration which you want to use, download the bitrise.yml first,
and save it into the root of your repository.
There's a button to quickly download the current bitrise.yml.

The original bitrise.yml you downloaded from bitrise.io
most likely includes the steps to retrieve your repository.
These steps will be redundant, as you will define how the repository should be accessed
in the "wrapper" config on bitrise.io,
so go ahead and remove the activate-ssh-key and git-clone
steps from it before you would commit it into your repository.

The "wrapper" config on bitrise.io which
defines how the repository have to be retrieved (e.g. through a Git Clone),
which workflows are exposed for bitrise.io builds,
and defines the automatic Trigger mapping.

Your build configuration (bitrise.yml), stored in your repository,
which defines what should happen during the builds.

This "wrapper" configuration
defines a common workflow _run_from_repo,
which will activate an SSH key (if specified), Git Clone the repository,
and then switch to use the bitrise.yml from the repository
by running bitrise run "${BITRISE_TRIGGERED_WORKFLOW_ID}".

This common workflow (_run_from_repo) is then used through other workflows, like
ci and another-workflow, using the after_runworkflow chaining
mechanism. Those workflows do not have any steps, the only thing
the ci and another-workflow workflows do is running the
common _run_from_repo workflow.

The trick is bitrise run "${BITRISE_TRIGGERED_WORKFLOW_ID}".
The BITRISE_TRIGGERED_WORKFLOW_ID environment variable is set to the
"entry" workflow, the one which started the build.
So, by running the ci workflow, the bitrise run "${BITRISE_TRIGGERED_WORKFLOW_ID}"
command will be the same as bitrise run "ci".

This makes it super simple and quick to expose workflows from your bitrise.yml (stored in your
repository) to bitrise.io, all you have to do is:

Define the workflow in your bitrise.yml (in your repository).

Clone the ci workflow (or the another-workflow) with a name matching the workflow
in your bitrise.yml (in your repository), or create a new empty workflow
with a matching name and add the _run_from_repo as an after_run workflow.
Note: in the Workflow Editor UI you can quickly clone a workflow by
selecting the workflow, then clicking the "add new workflow" (+) button.

This configuration will run the deploy workflow from your repository for every
code push on the master branch, the ci workflow from your repository for
every code push on other branches as well as for Pull Requests,
and it will never run another-workflow automatically, but you will be able
to start manual builds with another-workflow, which will invoke
the another-workflow workflow from the bitrise.yml in your repository.