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) + + + + + + + +