Document secrets via config and environment variables workflow (#212)

* document secrets via config * revision * typo * restructure * proofreading * Update github.md --------- Co-authored-by: Eduardo Blancas <[email protected]>
ploomber · May 2, 2024 · c9fff83 · c9fff83
1 parent c03a67b
commit c9fff83
Show file tree

Hide file tree

Showing 2 changed files with 87 additions and 5 deletions.
diff --git a/doc/user-guide/cli.md b/doc/user-guide/cli.md
@@ -197,6 +197,10 @@ On confirming with `y` the CLI will create a `ploomber-cloud.yaml` file in the p
 
 If your project uses secrets, you can define them in an `.env` file.
 
+```{important}
+If you are deploying using GitHub actions, **do not** upload your `.env` file to GitHub. Instead, follow the instructions [here.](../user-guide/github.md#secrets)
+```
+
 In your main project directory, create an `.env` file. Open it in your code editor, and enter your secrets. It should look like this:
 
 ```
@@ -213,12 +217,46 @@ 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.
 
-```{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.
+To learn how to read your secrets from within your application, see [Reading secrets.](../user-guide/secrets.md#reading-secrets)
+
+### Without an `.env` file
+
+You may also define secrets in your `ploomber-cloud.json` and Ploomber Cloud will read them from your environment variables. Here are the steps:
+
+1. Set secrets as environment variables using `export key=value`
+2. Define secret keys in `ploomber-cloud.json` under `secret-keys`
+3. Deploy via `ploomber-cloud 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 run `ploomber-cloud deploy`. You should see the secrets included with this message:
+
+```
+Adding the following secrets to the app: key1, key2,
 ```
 
-To learn how to read your secrets from within your application, see [Reading secrets.](./secrets.md)
+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.
 
 ## Configure resources
 

diff --git a/doc/user-guide/github.md b/doc/user-guide/github.md
@@ -3,7 +3,7 @@
 You can use GitHub Actions to deploy your project on each push.
 
 (set-key)=
-## Set Github secret
+## Set GitHub secret
 
 First, you need to get your [API key](../quickstart/apikey.md). Once you have the API
 key, you need to store it as a GitHub secret in your repository:
@@ -43,7 +43,7 @@ ploomber-cloud init
 `init` will create a `ploomber-cloud.json` file. For more information on the `init` command, see [](../user-guide/cli.md)
 
 (monitor)=
-## Configure and monitor Github actions
+## Configure and monitor GitHub actions
 
 Now, configure GitHub actions by adding [this YAML file](https://github.com/edublancas/cloud-template/blob/main/.github/workflows/ploomber-cloud.yaml) in `.github/workflows/ploomber-cloud.yaml`
 
@@ -125,3 +125,47 @@ If workflow needs an update a relevant message will be displayed:
 
 Please review the workflow file and update if needed.
 
+## Secrets
+
+To avoid uploading an `.env` file to GitHub, you may define them in your `ploomber-cloud.json` and Ploomber Cloud will read them from your repository secrets. Here are the steps:
+
+1. List the secret keys in `ploomber-cloud.json` under `secret-keys`
+2. Set the secrets in your GitHub repository and define them in your `ploomber-cloud.yaml` file
+3. Push your code to deploy
+
+For example, if you had two secrets, `key1` and `key2`, you should edit your `ploomber-cloud.json` to look like this:
+
+```json
+{
+  "id": "project-id-1999",
+  "type": "project-type",
+  "secret-keys": ["key1", "key2"]
+}
+```
+
+Set `key1` and `key2` as secrets in your GitHub repository using the same method you did for your [API key.](#set-github-secret) Now make sure to define them in your `ploomber-cloud.yaml` file. Here's an example snippet:
+
+```yaml
+- name: Deploy
+    env:
+      PLOOMBER_CLOUD_KEY: ${{ secrets.PLOOMBER_CLOUD_KEY }}
+      key1: ${{ secrets.key1 }}
+      key2: ${{ secrets.key2 }}
+    run: |
+      ploomber-cloud deploy --watch-incremental
+```
+
+Finally, push your code. In your deployment logs, when `ploomber-cloud deploy` is ran, you should see the secrets included with this message:
+
+```
+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 in GitHub, mention it in `ploomber-cloud.yaml`, AND mention it in `ploomber-cloud.json`. 
+    - If a secret is defined in `ploomber-cloud.json` but isn't set as a GitHub secret, the deployment will fail. 
+    - If a secret is set in GitHub but isn't defined in `ploomber-cloud.json`, that secret won't be included in the deployment.
+