Merge pull request platformsh#3510 from platformsh/git-23

Git 23

sites/platform/src/create-apps/app-reference.md

@@ -399,26 +399,37 @@ See some [examples of how to configure what's served](./web/_index.md).
 ### Web commands
 
 {{% version/specific %}}
+<!-- Version 1 -->
+
 | Name    | Type     | Required                      | Description |
 | ------- | -------- | ----------------------------- | ----------- |
+| `pre_start` | `string` |   | Command run just prior to `start`, which can be useful when you need to run _per-instance_ actions. |
 | `start` | `string` | See [note](#required-command) | The command to launch your app. If it terminates, it's restarted immediately. |
 
 <--->
+<!-- Version 2 -->
+
 | Name    | Type     | Required                      | Description |
 | ------- | -------- | ----------------------------- | ----------- |
 | `pre_start` | `string` |   | Command run just prior to `start`, which can be useful when you need to run _per-instance_ actions. See [Mounts, instances, and Network Storage](#mounts-instances-and-network-storage) for an example. |
 | `start` | `string` | See [note](#required-command) | The command to launch your app. If it terminates, it's restarted immediately. |
+
 {{% /version/specific %}}
 
 Example:
 
 {{% version/specific %}}
+<!-- Version 1 -->
+
 ```yaml {configFile="app"}
 web:
     commands:
         start: 'uwsgi --ini conf/server.ini'
 ```
+
 <--->
+<!-- Version 2 -->
+
 ```yaml {configFile="app"}
 applications:
     myapp:

sites/platform/src/define-routes/_index.md

@@ -383,6 +383,7 @@ all placeholders (`{default}` and `{all}`) are replaced with appropriate domain
 and any additional routes (such as redirecting HTTP to HTTPS) are created.
 This means the final generated routes differ by environment and so shouldn't be hard coded in your app.
 These routes are available in the `PLATFORM_ROUTES` environment variable as a base64-encoded JSON object.
+They are also available within an application container from the `/run/config.json` file so you can maintain a high number of routes more easily.
 
 To locate routes in a standardized fashion in any environment,
 you may specify an `id` for on each route.

sites/platform/src/development/variables/use-variables.md

@@ -379,7 +379,7 @@ and at runtime.
 | `{{< vendor/prefix >}}_PROJECT`          | Yes   | Yes     | The project ID. |
 | `{{< vendor/prefix >}}_PROJECT_ENTROPY`  | Yes   | Yes     | A random, 56-character value created at project creation and then stable throughout the project's life. Can be used for Drupal hash salts, Symfony secrets, and other similar values. |
 | `{{< vendor/prefix >}}_RELATIONSHIPS`    | No    | Yes     | A base64-encoded JSON object of relationships. The keys are the relationship name and the values are arrays of relationship endpoint definitions. The exact format is defined differently for each [service](../../add-services/_index.md). |
-| `{{< vendor/prefix >}}_ROUTES`           | No    | Yes     | A base64-encoded JSON object that describes the routes for the environment. It maps the content of your [routes configuration](../../define-routes/_index.md). |
+| `{{< vendor/prefix >}}_ROUTES`           | No    | Yes     | A base64-encoded JSON object that describes the routes for the environment. It maps the content of your [routes configuration](../../define-routes/_index.md). Note that this information is also available in your `/run/config.json` file. |
 | `{{< vendor/prefix >}}_SMTP_HOST`        | No    | Yes     | The SMTP host to send email messages through. Is empty when mail is disabled for the current environment. |
 | `{{< vendor/prefix >}}_SOURCE_DIR`       | Yes   | No      | The path to the root directory of your code repository in the context of a running [source operation](../../create-apps/source-operations.md). The directory contains a writable copy of your repository that you can commit to during the operation. |
 | `{{< vendor/prefix >}}_TREE_ID`          | Yes   | Yes     | The ID of the tree the application was built from, essentially the SHA hash of the tree in Git. Use when you need a unique ID for each build. |

sites/platform/src/environments/_index.md

@@ -4,6 +4,9 @@ weight: -75
 layout: single
 sidebarTitle: Manage environments
 description: Learn what environments on {{% vendor/name %}} are and how to take advantage of them.
+keywords:
+  - Git push options
+  - git push options
 ---
 
 A {{% vendor/name %}} environment contains one instance of an app (or [group of apps](../create-apps/multi-app/_index.md))
@@ -277,3 +280,35 @@ title=In the Console
 {{< /codetabs >}}
 
 The environment is redeployed and becomes available for use again.
+
+## Push options
+
+Git provides push options to pass a string to the server (see [the official Git documentation](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt)).
+
+{{% vendor/name %}} supports some of these push options,
+which allows you to push changes to your environment and trigger the following actions at the same time:
+
+| Action                                     | Command                                                                                                                 |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| Activate the environment                   | `git push {{% vendor/cli %}} -o "environment.status=active"`                                    |
+| Set a title for the environment            | `git push {{% vendor/cli %}} -o "environment.title=<ENVIRONMENT_TITLE>"`       |
+| Set the parent environment                 | `git push {{% vendor/cli %}} -o "environment.parent=<PARENT_ENVIRONMENT_NAME>"` |         
+| Clone the data from the parent environment | `git push {{% vendor/cli %}} -o "environment.clone_parent_on_create=True"` |
+| Disable the cloning of the data from the parent environment | `git push {{% vendor/cli %}} -o "environment.clone_parent_on_create=False"` |
+
+If your remote location isn't named `{{% vendor/cli %}}`,
+make sure you adjust the commands accordingly.
+
+{{< note >}}
+
+You can't use push options if you have a [source integration](/integrations/source/_index.md) set up.
+
+{{< /note >}}
+
+The following example shows how, through a single `push`,
+you can activate your environment, set a title for it,
+set a parent environment for it, and clone the data from its parent into it.
+
+```bash {location="Terminal"}
+git push {{% vendor/cli %}} -o "environment.status=active" -o "environment.title=my-environment-title" -o "environment.parent=my-parent-environment" -o "environment.clone_parent_on_create=True"
+```

sites/platform/src/environments/change-parent.md

@@ -45,3 +45,13 @@ So if you have the environment `new-feature` and want to change its parent to `m
 ```
 
 {{< /codetabs >}}
+
+If you're not using a [source integration](/integrations/source/_index.md),
+you can also set a parent for your environment when pushing changes to it.
+To do so, run the following command:
+
+```bash
+git push -o "environment.parent={{< variable "PARENT_ENVIRONMENT_NAME" >}}"
+```
+
+Learn more about how to [trigger actions on `push`](/environments/_index.md#push-options).

sites/platform/src/environments/deactivate-environment.md

@@ -93,3 +93,13 @@ Run the following command:
 ```
 
 {{< /codetabs >}}
+
+If you're not using a [source integration](/integrations/source/_index.md),
+you can also activate an environment when pushing changes to it.
+To do so, run the following command:
+
+```bash
+git push -o "environment.status=active"
+```
+
+Learn more about how to [trigger actions on `push`](/environments/_index.md#push-options).

sites/platform/src/integrations/activity/_index.md

@@ -149,6 +149,62 @@ There is also an `--exclude-environments` switch to excluded environments by nam
 As a general rule, it's better to have an activity script only execute on the specific events and branches you're interested in
 rather than firing on all activities and then filtering out undesired use cases in the script itself.
 
+## Activity script variables
+
+Some activities don't have access to [project and environment variables](/development/variables/_index.md#variable-types).
+In this case, to avoid hardcoding sensitive variables (such as API tokens) and therefore prevent security breaches,
+add a variable to your activity script.
+
+You can add activity script variables through the {{% vendor/name %}} CLI.
+Activity script variables are only visible in the activity script itself,
+inside the `variables` variable.
+
+### Add an activity script variable
+
+To add a variable to your activity script at the integration level,
+use the following `POST` request:
+
+```
+POST /api/projects/{{< variable "PROJECT_ID" >}}/integrations/{{< variable "INTEGRATION_ID" >}}/variables
+```
+
+You get a payload similar to the following:
+
+```
+{
+  "name": "string",
+  "attributes": {
+    "property1": "string",
+    "property2": "string"
+  },
+  "value": "string",
+  "is_json": true,
+  "is_sensitive": true,
+  "is_enabled": true
+}
+```
+
+### Delete or patch an activity script variable
+
+To delete an activity script variable,
+use the following `DELETE` request:
+
+```
+DELETE /api/projects/{{< variable "PROJECT_ID" >}}/integrations/{{< variable "INTEGRATION_ID" >}}/variables
+```
+
+You can also patch your activity script variable.
+To do so, send the same request using the `PATCH` method instead of the `DELETE` one.
+
+### List an activity script variable
+
+To list all your activity script variables at the integration level,
+use the following `GET` request:
+
+```
+GET /api/projects/{{< variable "PROJECT_ID" >}}/integrations/{{< variable "INTEGRATION_ID" >}}/variables
+```
+
 ## Available APIs
 
 Activity scripts can be written in ES2021 and don't support installing additional packages.