Merge branch 'russell/improve-environment-reference' into 'master'

Reformat CI/CD keywords reference document to new standard - environment

See merge request gitlab-org/gitlab!73519

doc/ci/yaml/index.md

@@ -2208,7 +2208,17 @@ In this example, the script:
 ### `environment`
 
 Use `environment` to define the [environment](../environments/index.md) that a job deploys to.
-For example:
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: The name of the environment the job deploys to, in one of these
+formats:
+
+- Plain text, including letters, digits, spaces and these characters: `-`, `_`, `/`, `$`, `{`, `}`.
+- CI/CD variables, including predefined, secure, or variables defined in the
+  `.gitlab-ci.yml` file. You can't use variables defined in a `script` section.
+
+**Example of `environment`**:
 
 ```yaml
 deploy to production:
@@ -2217,20 +2227,27 @@ deploy to production:
   environment: production
 ```
 
-You can assign a value to the `environment` keyword by using:
+**Additional details**:
 
-- Plain text, like `production`.
-- Variables, including CI/CD variables, predefined, secure, or variables
-  defined in the `.gitlab-ci.yml` file.
+- If you specify an `environment` and no environment with that name exists, an environment is
+  created.
 
-You can't use variables defined in a `script` section.
+#### `environment:name`
 
-If you specify an `environment` and no environment with that name exists,
-an environment is created.
+Set a name for an [environment](../environments/index.md).
 
-#### `environment:name`
+Common environment names are `qa`, `staging`, and `production`, but you can use any name.
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: The name of the environment the job deploys to, in one of these
+formats:
 
-Set a name for an [environment](../environments/index.md). For example:
+- Plain text, including letters, digits, spaces and these characters: `-`, `_`, `/`, `$`, `{`, `}`.
+- CI/CD variables, including predefined, secure, or variables defined in the
+  `.gitlab-ci.yml` file. You can't use variables defined in a `script` section.
+
+**Example of `environment:name`**:
 
 ```yaml
 deploy to production:
@@ -2240,32 +2257,19 @@ deploy to production:
     name: production
 ```
 
-Common environment names are `qa`, `staging`, and `production`, but you can use any
-name you want.
-
-You can assign a value to the `name` keyword by using:
-
-- Plain text, like `staging`.
-- Variables, including CI/CD variables, predefined, secure, or variables
-  defined in the `.gitlab-ci.yml` file.
+#### `environment:url`
 
-You can't use variables defined in a `script` section.
+Set a URL for an [environment](../environments/index.md).
 
-The environment `name` can contain:
+**Keyword type**: Job keyword. You can use it only as part of a job.
 
-- Letters
-- Digits
-- Spaces
-- `-`
-- `_`
-- `/`
-- `$`
-- `{`
-- `}`
+**Possible inputs**: A single URL, in one of these formats:
 
-#### `environment:url`
+- Plain text, like `https://prod.example.com`.
+- CI/CD variables, including predefined, secure, or variables defined in the
+  `.gitlab-ci.yml` file. You can't use variables defined in a `script` section.
 
-Set a URL for an [environment](../environments/index.md). For example:
+**Example of `environment:url`**:
 
 ```yaml
 deploy to production:
@@ -2276,16 +2280,10 @@ deploy to production:
     url: https://prod.example.com
 ```
 
-After the job completes, you can access the URL by using a button in the merge request,
-environment, or deployment pages.
-
-You can assign a value to the `url` keyword by using:
-
-- Plain text, like `https://prod.example.com`.
-- Variables, including CI/CD variables, predefined, secure, or variables
-  defined in the `.gitlab-ci.yml` file.
+**Additional details**:
 
-You can't use variables defined in a `script` section.
+- After the job completes, you can access the URL by selecting a button in the merge request,
+  environment, or deployment pages.
 
 #### `environment:on_stop`
 
@@ -2293,7 +2291,11 @@ Closing (stopping) environments can be achieved with the `on_stop` keyword
 defined under `environment`. It declares a different job that runs to close the
 environment.
 
-Read the `environment:action` section for an example.
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Additional details**:
+
+See [`environment:action`](#environmentaction) for more details and an example.
 
 #### `environment:action`
 
@@ -2364,10 +2366,19 @@ In the examples above, if the configuration is not identical:
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8.
 
-The `auto_stop_in` keyword is for specifying the lifetime of the environment,
-that when expired, GitLab automatically stops them.
+The `auto_stop_in` keyword specifies the lifetime of the environment. When an environment expires, GitLab
+automatically stops it.
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: A period of time written in natural language. For example,
+these are all equivalent:
 
-For example,
+- `168 hours`
+- `7 days`
+- `one week`
+
+**Example of `environment:auto_stop_in`**:
 
 ```yaml
 review_app:
@@ -2380,8 +2391,9 @@ review_app:
 When the environment for `review_app` is created, the environment's lifetime is set to `1 day`.
 Every time the review app is deployed, that lifetime is also reset to `1 day`.
 
-For more information, see
-[the environments auto-stop documentation](../environments/index.md#stop-an-environment-after-a-certain-time-period)
+**Related topics**:
+
+- [Environments auto-stop documentation](../environments/index.md#stop-an-environment-after-a-certain-time-period).
 
 #### `environment:kubernetes`
 
@@ -2390,7 +2402,9 @@ For more information, see
 Use the `kubernetes` keyword to configure deployments to a
 [Kubernetes cluster](../../user/infrastructure/clusters/index.md) that is associated with your project.
 
-For example:
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Example of `environment:kubernetes`**:
 
 ```yaml
 deploy:
@@ -2406,20 +2420,34 @@ This configuration sets up the `deploy` job to deploy to the `production`
 environment, using the `production`
 [Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/).
 
-For more information, see
-[Available settings for `kubernetes`](../environments/index.md#configure-kubernetes-deployments-deprecated).
+**Additional details**:
 
-NOTE:
-Kubernetes configuration is not supported for Kubernetes clusters
-that are [managed by GitLab](../../user/project/clusters/gitlab_managed_clusters.md).
-To follow progress on support for GitLab-managed clusters, see the
-[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/38054).
+- Kubernetes configuration is not supported for Kubernetes clusters
+  that are [managed by GitLab](../../user/project/clusters/gitlab_managed_clusters.md).
+  To follow progress on support for GitLab-managed clusters, see the
+  [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/38054).
+
+**Related topics**:
+
+- [Available settings for `kubernetes`](../environments/index.md#configure-kubernetes-deployments-deprecated).
 
 #### `environment:deployment_tier`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300741) in GitLab 13.10.
 
-Use the `deployment_tier` keyword to specify the tier of the deployment environment:
+Use the `deployment_tier` keyword to specify the tier of the deployment environment.
+
+**Keyword type**: Job keyword. You can use it only as part of a job.
+
+**Possible inputs**: One of the following:
+
+- `production`
+- `staging`
+- `testing`
+- `development`
+- `other`
+
+**Example of `environment:deployment_tier`**:
 
 ```yaml
 deploy:
@@ -2429,8 +2457,9 @@ deploy:
     deployment_tier: production
 ```
 
-For more information,
-see [Deployment tier of environments](../environments/index.md#deployment-tier-of-environments).
+**Related topics**:
+
+- [Deployment tier of environments](../environments/index.md#deployment-tier-of-environments).
 
 #### Dynamic environments