Variable inheritance works implicitly

The docs imply that one needs to use `dependencies` or `needs`
to gain variable inheritance in later jobs, but this isn't true. All jobs
in later stages will receive an inherited value without requiring
those keywords.

This change clarifies the documentation to reflect the observed
behavior. It also adds examples demonstrating how variable
inheritance can be turned off explicitly, and how inherited variables
may take precedence over other methods of variable definition.

The required format for the .env file is also explicitly stated, based
on its its implementation at:
https://gitlab.com/gitlab-org/gitlab/blob/2e5b4dbf3ab159f7ea4960d5fe7dfb06c7ed93e1/app/services/ci/parse_dotenv_artifact_service.rb#L55-58

doc/ci/variables/index.md

@@ -554,37 +554,45 @@ export GITLAB_USER_ID="42"
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22638) in GitLab 13.0.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217834) in GitLab 13.1.
 
-You can pass environment variables from one job to another job in a later stage.
+You can pass environment variables from one job to another job in a later stage
+through variable inheritance.
 These variables cannot be used as CI/CD variables to configure a pipeline, but
 they can be used in job scripts.
 
 1. In the job script, save the variable as a `.env` file.
+   - The format of the file must be one variable definition per line.
+   - Each defined line must be of the form `VARIABLE_NAME=ANY VALUE HERE`.
+   - Values can be wrapped in quotes, but cannot contain newline characters.
 1. Save the `.env` file as an [`artifacts:reports:dotenv`](../yaml/artifacts_reports.md#artifactsreportsdotenv)
 artifact.
-1. Set a job in a later stage to receive the artifact by using the [`dependencies`](../yaml/index.md#dependencies)
-   or the [`needs`](../yaml/index.md#needs) keywords.
-1. The later job can then [use the variable in scripts](#use-cicd-variables-in-job-scripts).
+1. Jobs in later stages can then [use the variable in scripts](#use-cicd-variables-in-job-scripts).
 
-For example, with the [`dependencies`](../yaml/index.md#dependencies) keyword:
+Inherited variables [take precedence](#cicd-variable-precedence) over
+certain types of new variable definitions such as job defined variables.
 
 ```yaml
 build:
   stage: build
   script:
-    - echo "BUILD_VERSION=hello" >> build.env
+    - echo "BUILD_VARIABLE=value_from_build_job" >> build.env
   artifacts:
     reports:
       dotenv: build.env
 
 deploy:
   stage: deploy
+  variables:
+    BUILD_VARIABLE: value_from_deploy_job
   script:
-    - echo "$BUILD_VERSION"  # Output is: 'hello'
-  dependencies:
-    - build
+    - echo "$BUILD_VARIABLE"  # Output is: 'value_from_build_job' due to precedence
 ```
 
-For example, with the [`needs:artifacts`](../yaml/index.md#needsartifacts) keyword:
+The [`dependencies`](../yaml/index.md#dependencies) or
+[`needs`](../yaml/index.md#needs) keywords can be used to control
+which jobs receive inherited values.
+
+To have no inherited dotenv environment variables, pass an empty `dependencies` or
+`needs` list, or pass [`needs:artifacts`](../yaml/index.md#needsartifacts) as `false`
 
 ```yaml
 build:
@@ -595,15 +603,46 @@ build:
     reports:
       dotenv: build.env
 
-deploy:
+deploy_one:
+  stage: deploy
+  script:
+    - echo "$BUILD_VERSION"  # Output is: 'hello'
+  dependencies:
+    - build
+
+deploy_two:
+  stage: deploy
+  script:
+    - echo "$BUILD_VERSION"  # Output is empty
+  dependencies: []
+
+deploy_three:
   stage: deploy
   script:
     - echo "$BUILD_VERSION"  # Output is: 'hello'
   needs:
-    - job: build
+    - build
+
+deploy_four:
+  stage: deploy
+  script:
+    - echo "$BUILD_VERSION"  # Output is: 'hello'
+  needs:
+    job: build
     artifacts: true
+
+deploy_five:
+  stage: deploy
+  script:
+    - echo "$BUILD_VERSION"  # Output is empty
+  needs:
+    job: build
+    artifacts: false
 ```
 
+[Multi-project pipelines](../pipelines/multi_project_pipelines.md#pass-cicd-variables-to-a-downstream-pipeline-by-using-variable-inheritance)
+can also inherit variables from their upstream pipelines.
+
 ## CI/CD variable precedence
 
 You can use CI/CD variables with the same name in different places, but the values