feat: added deployment modes section

sites/platform/src/learn/overview/build-deploy.md

@@ -85,6 +85,104 @@ but the file system is read-only.
 
 After the deploy process is over, any commands in your `post_deploy` hook are run.
 
+## Deployment types
+
+{{% vendor/name %}} supports two deployment types - automatic and manual. These types help to provide control over when changes are applied to staging and production environments.
+
+### Automatic deployment (default)
+
+This is the default behavior for all environments. With automatic deployment, changes like code pushes and variable updates are deployed immediately. This type of deployment is best suited for rapid iteration during development.
+
+### Manual deployment
+
+When enabled, manual deployment lets you control when deployments happen. This means that changes will be staged but not deployed until explicitly triggered by the user. This type of deployment is ideal for teams that want to bundle multiple changes and deploy them together in a controlled manner.
+
+When manual deployment is enabled in an environment, the following actions are queued until deployment is triggered:
+
+| Category             | Staged Activities |
+|----------------------|------------------|
+| **Code**             | `environment.push`, `environment.merge`, `environment.merge-pr` |
+| **Variables**        | `environment.variable.create`, `update`, `delete` |
+| **Resources**        | `environment.resources.update` |
+| **Domains & Routes** | `environment.domain.*`, `environment.route.*` |
+| **Environment Settings** | `environment.update.http_access`, `smtp`, `restrict_robots` |
+
+
+{{< note theme="info" >}}
+
+Note that development environments **always** use automatic deployment, while manual deployment is only available for staging and production environments.
+
+{{< /note >}}
+
+
+### Change deployment type
+
+You can adjust deployment behavior in your environment (staging or production only). To switch to manual, navigate to the environment settings in the Console and select the manual deployments option. To revert to automatic deployments, select the automatic deployments option.
+
+{{< note theme="tip" >}}
+
+If manual deployment is enabled, all currently staged changes will be deployed immediately and the environment will resume automatic deployment (default) behavior.
+
+{{< /note >}}
+
+### Trigger deployment manually
+
+Once manual deployment is enabled, eligible changes are staged. You can deploy them in the following ways:
+
+{{< codetabs >}}
+
++++
+title=Using the CLI
++++
+
+List environments with the following command:
+
+```bash
+platform environment:list
+
+```
+Then deploy the staged changes to a specific environment:
+
+```bash
+platform environment:deploy
+```
+
+The output should look similar to the example below:
+
+```bash
+Deploying staged changes:
++---------------+---------------------------+-----------------------------------------------------------+---------+
+| ID            | Created                   | Description                                               | Result  |
++---------------+---------------------------+-----------------------------------------------------------+---------+
+| 5uh3xwmkh5boq | 2024-11-22T14:01:10+00:00 | Patrick pushed to main                                    | failure |
+| fno2qiodq7e3c | 2024-11-22T13:06:18+00:00 | Arseni updated resource allocation on main                | success |
+| xzvcazrtoafeu | 2024-11-22T13:01:10+00:00 | Pilar added variable HELLO_WORLD to main                  | success |
+| fq73u53ruwloq | 2024-11-22T12:06:17+00:00 | Pilar pushed to main                                      | success |
++---------------+---------------------------+-----------------------------------------------------------+---------+
+```
+
+<--->
++++
+title=Using the Console
++++
+
+In the Console, a **Deploy** button will appear in the environment whenever changes are staged. You can review a summary of the pending changes before confirming the deployment.
+
+<--->
++++
+title=Using the API
++++
+
+Trigger the deployment of staged changes with the following:
+
+```bash
+
+POST /projects/{projectId}/environments/{environmentId}/deploy
+
+```
+
+{{< /codetabs >}}
+
 ## Deployment philosophy
 
 {{% vendor/name %}} values consistency over availability, acknowledging that it's nearly impossible to have both.

sites/upsun/src/learn/overview/build-deploy.md

@@ -85,6 +85,104 @@ but the file system is read-only.
 
 After the deploy process is over, any commands in your `post_deploy` hook are run.
 
+## Deployment types
+
+{{% vendor/name %}} supports two deployment types - automatic and manual. These types help to provide control over when changes are applied to staging and production environments.
+
+### Automatic deployment (default)
+
+This is the default behavior for all environments. With automatic deployment, changes like code pushes and variable updates are deployed immediately. This type of deployment is best suited for rapid iteration during development.
+
+### Manual deployment
+
+When enabled, manual deployment lets you control when deployments happen. This means that changes will be staged but not deployed until explicitly triggered by the user. This type of deployment is ideal for teams that want to bundle multiple changes and deploy them together in a controlled manner.
+
+When manual deployment is enabled in an environment, the following actions are queued until deployment is triggered:
+
+| Category             | Staged Activities |
+|----------------------|------------------|
+| **Code**             | `environment.push`, `environment.merge`, `environment.merge-pr` |
+| **Variables**        | `environment.variable.create`, `update`, `delete` |
+| **Resources**        | `environment.resources.update` |
+| **Domains & Routes** | `environment.domain.*`, `environment.route.*` |
+| **Environment Settings** | `environment.update.http_access`, `smtp`, `restrict_robots` |
+
+
+{{< note theme="info" >}}
+
+Note that development environments **always** use automatic deployment, while manual deployment is only available for staging and production environments.
+
+{{< /note >}}
+
+
+### Change deployment type
+
+You can adjust deployment behavior in your environment (staging or production only). To switch to manual, navigate to the environment settings in the Console and select the manual deployments option. To revert to automatic deployments, select the automatic deployments option.
+
+{{< note theme="tip" >}}
+
+If manual deployment is disabled, all currently staged changes will be deployed immediately and the environment will resume automatic deployment (default) behavior.
+
+{{< /note >}}
+
+### Trigger deployment manually
+
+Once manual deployment is enabled, eligible changes are staged. You can deploy them in the following ways:
+
+{{< codetabs >}}
+
++++
+title=Using the CLI
++++
+
+List environments with the following command:
+
+```bash
+upsun environment:list
+
+```
+Then deploy the staged changes to a specific environment:
+
+```bash
+upsun environment:deploy
+```
+
+The output should look similar to the example below:
+
+```bash
+Deploying staged changes:
++---------------+---------------------------+-----------------------------------------------------------+---------+
+| ID            | Created                   | Description                                               | Result  |
++---------------+---------------------------+-----------------------------------------------------------+---------+
+| 5uh3xwmkh5boq | 2024-11-22T14:01:10+00:00 | Patrick pushed to main                                    | failure |
+| fno2qiodq7e3c | 2024-11-22T13:06:18+00:00 | Arseni updated resource allocation on main                | success |
+| xzvcazrtoafeu | 2024-11-22T13:01:10+00:00 | Pilar added variable HELLO_WORLD to main                  | success |
+| fq73u53ruwloq | 2024-11-22T12:06:17+00:00 | Pilar pushed to main                                      | success |
++---------------+---------------------------+-----------------------------------------------------------+---------+
+```
+
+<--->
++++
+title=Using the Console
++++
+
+In the Console, a **Deploy** button will appear in the environment whenever changes are staged. You can review a summary of the pending changes before confirming the deployment.
+
+<--->
++++
+title=Using the API
++++
+
+Trigger the deployment of staged changes with the following:
+
+```bash
+
+POST /projects/{projectId}/environments/{environmentId}/deploy
+
+```
+
+{{< /codetabs >}}
+
 ## Deployment philosophy
 
 {{% vendor/name %}} values consistency over availability, acknowledging that it's nearly impossible to have both.