Use a Linux/Android stack and set the environment docker image for the app (Settings tab)

The first option is strongly preferred, you should not change the base environment docker image (on the Settings tab on bitrise.io)
unless you really have to! Running the docker commands yourself during the build is way more flexible,
and provides an overall better control.

Use a Linux/Android stack and set the environment docker image for the app (Settings tab)

Custom Android docker image

Creating and maintaining your own Android Docker image can be quite time consuming!
If what you need is just to install a couple of additional tools, you should do that with e.g. a Script step instead!
For more information see the Install Any Additional Tool guide.
You should only use your own Android docker image if you really have to!

If you want to run your build in a custom docker environment,
you should base your own docker image on one of our base Docker images, as those have every base tool pre-installed,
the standard bitrise directories created, the Environments (like $BITRISE_DEPLOY_DIR) set,
and are pre-cached on the build virtual machines.
If you decide to create your own Docker image please read this guide, from start to finish!

Feel free to send Pull Request for our images if you think we missed something, which would be useful for everyone who uses our images!

As you can see, if you want to base your own image on one of our available images you can do that by specifying
it at the very top of your Dockerfile with a FROM bitriseio/IMAGE-ID:latest,
for example: FROM bitriseio/docker-bitrise-base:latest

Don't use the -alpha images for your builds

For every docker image we have on Docker Hub we have a -alpha post fixed version too.
the -alpha ones are rebuilt frequently and are not precached on bitrise.io,
so you should avoid those. The only purpose of the -alpha images is to provide
ready to use test environments for us, before we would publish a non -alpha version.

Important: you have to use the Docker Hub ID of the image you want to use as
the base image (ex: bitriseio/docker-android, bitriseio/android-ndk or bitriseio/docker-bitrise-base).

If you don't need the Android tools you should base your image on
the bitrise-base (bitriseio/docker-bitrise-base) image
and install just the things you need.

If you need the Android tools then you should use
the android (bitriseio/docker-android) image
or the bitrise-base (bitriseio/docker-bitrise-base) image.

You should only use the android-ndk (bitriseio/android-ndk) image
as the base image if you actually need the NDK.

From a performance perspective: you should install the least amount of tools in your image,
as it'll make your image smaller, which means faster download & build start.

You now have the description of your image. Go to Docker Hub, click Create in the top menu and select Create Automated Build.
If you haven't linked your GitHub account to your Docker Hub account you'll have to do it now.
Once the link between GitHub and Docker Hub is established you'll see a list of your GitHub repositories.
Select the repository you just created (the one with the Dockerfile in its root), and follow the guide.

Congratulation! You now have a fully automatic Docker image creation, based on your GitHub repository!
This means that every time you change the repository, commit & push the change Docker Hub will pick up the new Dockerfile and will build a Docker image for you.

One more thing you should do is to Link your image to our base image you use, so that every time our base image is updated your image will update as well.

This is especially important if you base your Docker image on one of our Android images.
Those images are quite large, and if we have to do a change in the base Docker image and you don't build a new image,
your image will require the old base image, which won't be pre-cached on the build Virtual Machines anymore!
This means that to docker pull your image it won't be enough to download just the diffs anymore,
the whole image will have to be pulled which might even result in errors like "no space left on the device" -
to docker pull the base Android image, if no cache is available, it already requires ~10GB disk space, and the Android NDK image is even larger!

Link your image to one of ours: you can do this on DockerHub, on the Build Settings tab,
under the Repository Links section. Just specify the ID of our Docker image (ex: bitriseio/docker-android),
save the link and the next time the specified image is updated your image will be re-built as well (using the Dockerfile in your repository).