diff --git a/doc/static/github/confirm-prod.png b/doc/static/github/confirm-prod.png
new file mode 100644
index 00000000..c26587b1
Binary files /dev/null and b/doc/static/github/confirm-prod.png differ
diff --git a/doc/static/github/env-secret.png b/doc/static/github/env-secret.png
new file mode 100644
index 00000000..05f3fd9a
Binary files /dev/null and b/doc/static/github/env-secret.png differ
diff --git a/doc/static/github/final-config.png b/doc/static/github/final-config.png
new file mode 100644
index 00000000..a6e0e583
Binary files /dev/null and b/doc/static/github/final-config.png differ
diff --git a/doc/static/github/new-env.png b/doc/static/github/new-env.png
new file mode 100644
index 00000000..96f2f16e
Binary files /dev/null and b/doc/static/github/new-env.png differ
diff --git a/doc/static/github/prod-env.png b/doc/static/github/prod-env.png
new file mode 100644
index 00000000..cf388d59
Binary files /dev/null and b/doc/static/github/prod-env.png differ
diff --git a/doc/static/github/review-pending.png b/doc/static/github/review-pending.png
new file mode 100644
index 00000000..cc5e8a1b
Binary files /dev/null and b/doc/static/github/review-pending.png differ
diff --git a/doc/static/github/reviewers.png b/doc/static/github/reviewers.png
new file mode 100644
index 00000000..9352327e
Binary files /dev/null and b/doc/static/github/reviewers.png differ
diff --git a/doc/user-guide/github.md b/doc/user-guide/github.md
index 2ba27df5..9a566a97 100644
--- a/doc/user-guide/github.md
+++ b/doc/user-guide/github.md
@@ -171,3 +171,74 @@ Some important notes:
     - 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.
 
+
+## Deployment environments
+
+For simple scenarios, you can opt for the basic deployment strategy outlined in [this section](monitor).
+If you need separate deployment environments with their own protection rules and secrets, you can use GitHub [environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment).
+Here's a step-by-step guide to configuring two environments `dev` and `prod`. `dev` deployments happen automatically whenever code changes are pushed to the `main` branch. However, `prod` deployments are started only when `dev` deployments are successful and the deployment has been approved by a reviewer.
+
+
+### Create environment
+
+Navigate to the repository `Settings` page and then `Environments`. Click on `New Environment`:
+
+![](../static/github/new-env.png)
+
+Name the environment as `prod` and click on `Configure environment`:
+
+![](../static/github/prod-env.png)
+
+Add usernames of reviewers who can approve the production deployments:
+
+![](../static/github/reviewers.png)
+
+You also need to add the `PLOOMBER_CLOUD_KEY` as an environment secret. Refer to the [API key](../quickstart/apikey.md) guide for more information.
+
+![](../static/github/env-secret.png)
+
+Once the environment is configured it should look like this:
+
+![](../static/github/final-config.png)
+
+### Configuration files
+
+Next we will create two separate config files `ploomber-cloud.dev.json` and `ploomber-cloud.prod.json`:
+
+```sh 
+ploomber-cloud init --config ploomber-cloud.dev.json
+```
+
+```sh 
+ploomber-cloud init --config ploomber-cloud.prod.json
+```
+
+You may configure special resources for the production environment by running:
+
+```sh 
+ploomber-cloud resources
+```
+
+To learn more about configuration files click [here](https://docs.cloud.ploomber.io/en/latest/user-guide/cli.html#switching-the-configuration-file).
+
+### Configure deployment
+
+Next, we will configure `dev` and `prod` deployments by adding a workflow file to the path `.github/workflows` in the repository's root folder. You can use this [template](https://github.com/edublancas/cloud-template/blob/main/.github/workflows/ploomber-cloud-env.yaml).
+We have added two jobs for `dev` and `prod` respectively for demonstration purposes. But you may add as many jobs as needed, one for each environment.
+If you create config files with different names ensure to pass them correctly using the `--config` flag.
+
+Once the workflow file has been pushed to GitHub, the `dev` deployment will be triggered. If the `dev` deployment is completed successfully, the `prod` deployment will be marked for approval from reviewers.
+
+![](../static/github/review-pending.png)
+
+The reviewer needs to click on `Approve and Deploy` for the deployment to get triggered.
+
+![](../static/github/confirm-prod.png)
+
+
+
+
+
+
+
+