diff --git a/test/README.md b/test/README.md
index abd8e854..72732ea4 100644
--- a/test/README.md
+++ b/test/README.md
@@ -58,3 +58,52 @@ To get the latest images you need to update it manually (in order not to poll
 GitHub every time):
 
     $ make -B bots
+
+## GitHub integration
+
+Tests are automatically triggered for every pull request. To disable tests for
+a pull request, add the `no-test` label when opening it.
+
+To interact with GitHub from scripts in `bots/`, generate [a
+token](https://github.com/settings/tokens) with at least *repo:status*,
+*public_repo*, and *read:org* permissions, and put it into
+`~/.config/github-token`.
+
+You can retry a failed test with:
+
+    $ bots/tests-trigger --repo weldr/lorax <PR> <test>
+
+If no test is given, all failed tests will be retried. Pass `--allow` to
+trigger tests on a pull request by an outside contributor.
+
+
+## Azure setup
+
+To authenticate Ansible (used in tests) with Azure you need to set the following
+environment variables:
+`AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT`, `AZURE_CLIENT_ID` and `AZURE_SECRET`.
+
+From the left-hand side menu at https://portal.azure.com select
+*Resource groups* >> *Click on composer RG*. Above the resulting list of resources
+you can see *Subscription ID* -> `AZURE_SUBSCRIPTION_ID`.
+
+From the left-hand side menu at https://portal.azure.com select
+*Azure Active Directory* >> *App registrations* >> New registration. Give it a name
+and leave the rest with default values. Once the AD application has been created
+you can click on its name to view its properties. There you have:
+
+* Directory (tenant) ID -> `AZURE_TENANT`
+* Application (client) ID -> `AZURE_CLIENT_ID`
+* Certificates & secrets (on the left) >> New client secret -> `AZURE_SECRET`
+
+Next make sure the newly created AD App has access to the storage account.
+From the left-hand side menu at https://portal.azure.com select
+*Storage accounts* >> *composerredhat* >> *Access control (IAM)* >>
+*Role assignments* >> *Add* >> *Add role assignment*. Then make sure to select
+- Role == Contributor
+- Scope == Resource group (Inherited)
+- AD app name (not the user owning the application)
+
+
+Storage account itself must be of type **StorageV2** so tests can upload blobs
+to it!
diff --git a/tests/cli/test_build_and_deploy_azure.sh b/tests/cli/test_build_and_deploy_azure.sh
index 7dbe27d9..7c8eeec4 100755
--- a/tests/cli/test_build_and_deploy_azure.sh
+++ b/tests/cli/test_build_and_deploy_azure.sh
@@ -17,6 +17,8 @@ CLI="${CLI:-./src/bin/composer-cli}"
 
 rlJournalStart
     rlPhaseStartSetup
+        # NOTE: see test/README.md for information how to obtain these
+        # UUIDs and what configuration is expected on the Azure side
         if [ -z "$AZURE_SUBSCRIPTION_ID" ]; then
             rlFail "AZURE_SUBSCRIPTION_ID is empty!"
         else