From 9f1ba61cb8be4afefafbd1ebb4fbb4d2312e4296 Mon Sep 17 00:00:00 2001
From: "Vipul Gupta (@vipulgupta2048)" <vipul@balena.io>
Date: Thu, 3 Nov 2022 04:49:26 +0530
Subject: [PATCH] patch: Document need for balena publish/finalize API secret

Signed-off-by: Vipul Gupta (@vipulgupta2048) <vipul@balena.io>
---
 README.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 57a4998ea..2d8adc6da 100644
--- a/README.md
+++ b/README.md
@@ -190,10 +190,18 @@ An example of multiple bake targets can be found here: <https://github.com/balen
 
 ### balena
 
-If a `balena.yml` file is found in the root of the repository Flowzone will attempt to push draft releases to your application slug(s) and finalize on merge.
+If a `balena.yml` file is found in the root of the repository Flowzone will attempt to push draft releases to your fleet's slug(s) and finalize on merge.
+
+This will **require** your organization or your repository to have an API key secret named as `BALENA_API_KEY` set in GitHub. If you intend to set an org level secret then make sure the API key is valid for all repositories in that organization. A repository level secret will override an organization level secret. This API key will be used to login into balena and push draft releases to your fleet. 
 
 To disable publishing of releases to balenaCloud set [`balena_slugs`](#balena_slugs) to `""`.
 
+Examples:
+
+1. Start with something simple, [balena-python-hello-world](https://github.com/balena-io-examples/balena-python-hello-world/blob/master/.github/workflows/flowzone.yml)
+2. Push to multiple fleets, check out [balena-supervisor](https://github.com/balena-os/balena-supervisor/blob/master/.github/workflows/flowzone.yml).
+
+
 ### Python (with Poetry)
 
 Python tests will be run if a `pyproject.toml` file is found in the root of the repository and Poetry is used as a package manager.