Document secrets via config and environment variables workflow

doc/user-guide/cli.md

@@ -207,13 +207,12 @@ ploomber-cloud deploy
 The command-line interface will automatically read and encrypt your secrets and include them in the deployment.
 For security reasons, your `.env` file is replaced with an empty file at runtime. Ploomber only stores your encrypted secrets.
 
+To learn how to read your secrets from within your application, see [Reading secrets.](../user-guide/secrets.md#reading-secrets)
+
 ```{note}
-Ensure that you specify all the required secrets in the `.env` file whenever deploying or re-deploying an application. Secrets will not be carried over from the previous deployment.
+We generally advise users to define secrets through an `.env` file. In the case this isn't possible, we've created an [alternative solution.](../user-guide/github.md#secrets)
 ```
 
-To learn how to read your secrets from within your application, see [Reading secrets.](./secrets.md)
-
-
 ## Configure resources
 
 You can customize the amount of `CPUs`, `RAM`, and `GPUs` that your project will use with this command:

doc/user-guide/github.md

@@ -125,3 +125,42 @@ If workflow needs an update a relevant message will be displayed:
 
 Please review the workflow file and update if needed.
 
+## Secrets
+
+We generally advise users to define their secrets in an `.env` file. However, this isn't optimal in the case of Github deployment, since uploading an `.env` file would expose your plain secrets.
+
+As a result, we've created a workflow where the CLI can read secrets from your local environment. To take advantage of this, follow these steps:
+
+1. Set secrets as environment variables using `export key=value`
+2. Define secret keys in `ploomber-cloud.json` under `secret-keys`
+3. Push your code to deploy
+
+For example, if I had two secrets, `key1` and `key2`, I would first set them as environment variables:
+
+```sh
+export key1=val1
+export key2=val2
+```
+
+Then I would edit my `ploomber-cloud.json` to look like this:
+
+```json
+"id": "project-id-1999",
+"type": "project-type",
+"secret-keys": ["key1", "key2"]
+```
+
+Now, in your deployment logs, when `ploomber-cloud deploy` is ran, you should see the secrets included with this message:
+
+```sh
+Adding the following secrets to the app: key1, key2,
+```
+
+Some important notes:
+
+- `secret-keys` should be defined as a list of strings that only includes the keys (not the values) of each secret
+- If your secrets are defined in both an `.env` and `secret-keys`, the deployment will fail. You may only use one method.
+- Make sure to define each secret as an environment variable AND in your `ploomber-cloud.json`. 
+    - If a secret is defined in `ploomber-cloud.json`, but isn't set as an environment variable, the deployment will fail. 
+    - If a secret is set as an environment variable, but isn't defined in `ploomber-cloud.json`, that secret won't be included in the deployment.
+