Merge branch 'docs-ci-variables-cleanup-1' into 'master'

Start cleaning up CI/CD variables documentation

See merge request gitlab-org/gitlab!57464

app/views/admin/application_settings/ci/_header.html.haml

@@ -8,7 +8,7 @@
 
 %p
   = _('Variables store information, like passwords and secret keys, that you can use in job scripts. All projects on the instance can use these variables.')
-  = link_to s_('Learn more.'), help_page_path('ci/variables/README', anchor: 'instance-level-cicd-variables'), target: '_blank', rel: 'noopener noreferrer'
+  = link_to s_('Learn more.'), help_page_path('ci/variables/README', anchor: 'instance-cicd-variables'), target: '_blank', rel: 'noopener noreferrer'
 %p
   = _('Variables can be:')
 %ul
@@ -16,4 +16,4 @@
     = html_escape(_('%{code_open}Protected:%{code_close} Only exposed to protected branches or tags.')) % { code_open: '<code>'.html_safe, code_close: '</code>'.html_safe }
   %li
     = html_escape(_('%{code_open}Masked:%{code_close} Hidden in job logs. Must match masking requirements.')) % { code_open: '<code>'.html_safe, code_close: '</code>'.html_safe }
-    = link_to _('Learn more.'), help_page_path('ci/variables/README', anchor: 'masked-variable-requirements'), target: '_blank', rel: 'noopener noreferrer'
+    = link_to _('Learn more.'), help_page_path('ci/variables/README', anchor: 'mask-a-cicd-variable'), target: '_blank', rel: 'noopener noreferrer'

app/views/admin/application_settings/ci_cd.html.haml

@@ -8,7 +8,7 @@
   .settings-content
     - if ci_variable_protected_by_default?
       %p.settings-message.text-center
-        - link_start = '<a href="%{url}">'.html_safe % { url: help_page_path('ci/variables/README', anchor: 'protect-a-custom-variable') }
+        - link_start = '<a href="%{url}">'.html_safe % { url: help_page_path('ci/variables/README', anchor: 'protect-a-cicd-variable') }
         = s_('Environment variables on this GitLab instance are configured to be %{link_start}protected%{link_end} by default.').html_safe % { link_start: link_start, link_end: '</a>'.html_safe }
     #js-instance-variables{ data: { endpoint: admin_ci_variables_path, group: 'true', maskable_regex: ci_variable_maskable_regex, protected_by_default: ci_variable_protected_by_default?.to_s} }
 

app/views/ci/variables/_content.html.haml

@@ -7,4 +7,4 @@
     = html_escape(_('%{code_open}Protected:%{code_close} Only exposed to protected branches or tags.')) % { code_open: '<code>'.html_safe, code_close: '</code>'.html_safe }
   %li
     = html_escape(_('%{code_open}Masked:%{code_close} Hidden in job logs. Must match masking requirements.')) % { code_open: '<code>'.html_safe, code_close: '</code>'.html_safe }
-    = link_to _('Learn more.'), help_page_path('ci/variables/README', anchor: 'masked-variable-requirements'), target: '_blank', rel: 'noopener noreferrer'
+    = link_to _('Learn more.'), help_page_path('ci/variables/README', anchor: 'mask-a-cicd-variable'), target: '_blank', rel: 'noopener noreferrer'

app/views/ci/variables/_index.html.haml

@@ -2,7 +2,7 @@
 
 - if ci_variable_protected_by_default?
   %p.settings-message.text-center
-    - link_start = '<a href="%{url}">'.html_safe % { url: help_page_path('ci/variables/README', anchor: 'protect-a-custom-variable') }
+    - link_start = '<a href="%{url}">'.html_safe % { url: help_page_path('ci/variables/README', anchor: 'protect-a-cicd-variable') }
     = s_('Environment variables are configured by your administrator to be %{link_start}protected%{link_end} by default.').html_safe % { link_start: link_start, link_end: '</a>'.html_safe }
 
 - is_group = !@group.nil?
@@ -16,7 +16,7 @@
   aws_tip_deploy_link: help_page_path('ci/cloud_deployment/index.md', anchor: 'deploy-your-application-to-the-aws-elastic-container-service-ecs'),
   aws_tip_commands_link: help_page_path('ci/cloud_deployment/index.md', anchor: 'run-aws-commands-from-gitlab-cicd'),
   aws_tip_learn_link: help_page_path('ci/cloud_deployment/index.md', anchor: 'aws'),
-  protected_environment_variables_link: help_page_path('ci/variables/README', anchor: 'protect-a-custom-variable'),
+  protected_environment_variables_link: help_page_path('ci/variables/README', anchor: 'protect-a-cicd-variable'),
   masked_environment_variables_link: help_page_path('ci/variables/README', anchor: 'mask-a-custom-variable'),
 } }
 

app/views/ci/variables/_variable_row.html.haml

@@ -39,7 +39,7 @@
         = value
       %p.masking-validation-error.gl-field-error.hide
         = s_("CiVariables|Cannot use Masked Variable with current value")
-        = link_to sprite_icon('question-o'), help_page_path('ci/variables/README', anchor: 'mask-a-custom-variable'), target: '_blank', rel: 'noopener noreferrer'
+        = link_to sprite_icon('question-o'), help_page_path('ci/variables/README', anchor: 'mask-a-cicd-variable'), target: '_blank', rel: 'noopener noreferrer'
     - unless only_key_value
       .ci-variable-body-item.ci-variable-protected-item.table-section.section-20.mr-0.border-top-0
         .gl-mr-3

doc/ci/cloud_deployment/ecs/quick_start_guide.md

@@ -211,7 +211,7 @@ Do not share the secret access key in a public place. You must save it in a secu
 
 ### Setup credentials in GitLab to let pipeline jobs access to ECS
 
-You can register the access information in [GitLab Environment Variables](../../variables/README.md#create-a-custom-variable-in-the-ui).
+You can register the access information in [GitLab Environment Variables](../../variables/README.md#custom-cicd-variables).
 These variables are injected into the pipeline jobs and can access the ECS API.
 
 1. Go to **ecs-demo** project on GitLab.

doc/ci/cloud_deployment/index.md

@@ -117,7 +117,7 @@ After you have these prerequisites ready, follow these steps:
 1. Make sure your AWS credentials are set up as CI/CD variables for your
    project. You can follow [the steps above](#run-aws-commands-from-gitlab-cicd) to complete this setup.
 1. Add these variables to your project's `.gitlab-ci.yml` file, or in the project's
-   [CI/CD settings](../variables/README.md#create-a-custom-variable-in-the-ui):
+   [CI/CD settings](../variables/README.md#custom-cicd-variables):
 
    - `CI_AWS_ECS_CLUSTER`: The name of the AWS ECS cluster that you're targeting for your deployments.
    - `CI_AWS_ECS_SERVICE`: The name of the targeted service tied to your AWS ECS cluster.
@@ -146,7 +146,7 @@ After you have these prerequisites ready, follow these steps:
    ```
 
    You can create your `CI_AWS_ECS_TASK_DEFINITION_FILE` variable as a
-   [file-typed CI/CD variable](../variables/README.md#custom-cicd-variables-of-type-file) instead of a
+   [file-typed CI/CD variable](../variables/README.md#cicd-variable-types) instead of a
    regular CI/CD variable. If you choose to do so, set the variable value to be the full contents of
    the JSON task definition. You can then remove the JSON file from your project.
 
@@ -257,7 +257,7 @@ pass three JSON input objects, based on existing templates:
        CI_AWS_EC2_DEPLOYMENT_FILE: 'aws/create_deployment.json'
      ```
 
-   - Alternatively, you can provide these JSON objects as [file-typed CI/CD variables](../variables/README.md#custom-cicd-variables-of-type-file).
+   - Alternatively, you can provide these JSON objects as [file-typed CI/CD variables](../variables/README.md#cicd-variable-types).
      In your project, go to **Settings > CI/CD > Variables** and add
      the three variables listed above as file-typed CI/CD variables.
      For each variable, set the value to its corresponding JSON object.

doc/ci/environments/deployment_safety.md

@@ -110,7 +110,7 @@ for an explanation of these roles and the permissions of each.
 
 Production secrets are needed to deploy successfully. For example, when deploying to the cloud,
 cloud providers require these secrets to connect to their services. In the project settings, you can
-define and protect CI/CD variables for these secrets. [Protected variables](../variables/README.md#protect-a-custom-variable)
+define and protect CI/CD variables for these secrets. [Protected variables](../variables/README.md#protect-a-cicd-variable)
 are only passed to pipelines running on [protected branches](../../user/project/protected_branches.md)
 or [protected tags](../../user/project/protected_tags.md).
 The other pipelines don't get the protected variable. You can also

doc/ci/migration/circleci.md

@@ -265,7 +265,7 @@ test_async:
 
 ## Contexts and variables
 
-CircleCI provides [Contexts](https://circleci.com/docs/2.0/contexts/) to securely pass environment variables across project pipelines. In GitLab, a [Group](../../user/group/index.md) can be created to assemble related projects together. At the group level, [CI/CD variables](../variables/README.md#group-level-cicd-variables) can be stored outside the individual projects, and securely passed into pipelines across multiple projects.
+CircleCI provides [Contexts](https://circleci.com/docs/2.0/contexts/) to securely pass environment variables across project pipelines. In GitLab, a [Group](../../user/group/index.md) can be created to assemble related projects together. At the group level, [CI/CD variables](../variables/README.md#group-cicd-variables) can be stored outside the individual projects, and securely passed into pipelines across multiple projects.
 
 ## Orbs
 

doc/ci/migration/jenkins.md

@@ -305,7 +305,7 @@ my_job:
 
 In GitLab, we use the [`variables` keyword](../yaml/README.md#variables) to define different variables at runtime.
 These can also be set up through the GitLab UI, under CI/CD settings. See also our [general documentation on variables](../variables/README.md),
-including the section on [protected variables](../variables/README.md#protect-a-custom-variable) which can be used
+including the section on [protected variables](../variables/README.md#protect-a-cicd-variable) which can be used
 to limit access to certain variables to certain environments or runners:
 
 ```yaml

doc/ci/secrets/index.md

@@ -114,7 +114,7 @@ In this example:
 
 After GitLab fetches the secret from Vault, the value is saved in a temporary file.
 The path to this file is stored in a CI/CD variable named `DATABASE_PASSWORD`,
-similar to [variables of type `file`](../variables/README.md#custom-cicd-variables-of-type-file).
+similar to [variables of type `file`](../variables/README.md#cicd-variable-types).
 
 For more information about the supported syntax, read the
 [`.gitlab-ci.yml` reference](../yaml/README.md#secretsvault).

doc/ci/services/index.md

@@ -189,7 +189,7 @@ To override the default behavior, you can
 
 You can also pass custom CI/CD [variables](../variables/README.md)
 to fine tune your Docker `images` and `services` directly in the `.gitlab-ci.yml` file.
-For more information, read about [`.gitlab-ci.yml` defined variables](../variables/README.md#gitlab-ciyml-defined-variables).
+For more information, read about [`.gitlab-ci.yml` defined variables](../variables/README.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file).
 
 ```yaml
 # The following variables are automatically passed down to the Postgres container

doc/ci/services/mysql.md

@@ -14,7 +14,7 @@ need it for your tests to run.
 
 If you want to use a MySQL container, you can use [GitLab Runner](../runners/README.md) with the Docker executor.
 
-1. [Create CI/CD variables](../variables/README.md#create-a-custom-variable-in-the-ui) for your
+1. [Create CI/CD variables](../variables/README.md#custom-cicd-variables) for your
    MySQL database and password by going to **Settings > CI/CD**, expanding **Variables**,
    and clicking **Add Variable**.
 

doc/ci/services/postgres.md

@@ -31,7 +31,7 @@ variables:
 
 To set values for the `POSTGRES_DB`, `POSTGRES_USER`,
 `POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD`,
-[assign them to a CI/CD variable in the user interface](../variables/README.md#create-a-custom-variable-in-the-ui),
+[assign them to a CI/CD variable in the user interface](../variables/README.md#custom-cicd-variables),
 then assign that variable to the corresponding variable in your
 `.gitlab-ci.yml` file.
 

doc/ci/triggers/README.md

@@ -192,7 +192,7 @@ source repository. Be sure to URL-encode `ref` if it contains slashes.
 
 If you trigger a pipeline by using a webhook, you can access the webhook payload with
 the `TRIGGER_PAYLOAD` [predefined CI/CD variable](../variables/predefined_variables.md).
-The payload is exposed as a [file-type variable](../variables/README.md#custom-cicd-variables-of-type-file),
+The payload is exposed as a [file-type variable](../variables/README.md#cicd-variable-types),
 so you can access the data with `cat $TRIGGER_PAYLOAD` or a similar command.
 
 ## Making use of trigger variables

doc/ci/yaml/README.md

@@ -1229,7 +1229,7 @@ expression string per rule, rather than an array of them. Any set of expressions
 evaluated can be [conjoined into a single expression](../variables/README.md#conjunction--disjunction)
 by using `&&` or `||`, and the [variable matching operators (`==`, `!=`, `=~` and `!~`)](../variables/README.md#syntax-of-cicd-variable-expressions).
 
-Unlike variables in [`script`](../variables/README.md#syntax-of-cicd-variables-in-job-scripts)
+Unlike variables in [`script`](../variables/README.md#use-cicd-variables-in-job-scripts)
 sections, variables in rules expressions are always formatted as `$VARIABLE`.
 
 `if:` clauses are evaluated based on the values of [predefined CI/CD variables](../variables/predefined_variables.md)

doc/development/dangerbot.md

@@ -156,7 +156,7 @@ is not shared to forks. To work around this, you can add an [environment
 variable](../ci/variables/README.md) called `DANGER_GITLAB_API_TOKEN` with a
 personal API token to your fork. That way the danger comments are made from CI
 using that API token instead. Making the variable
-[masked](../ci/variables/README.md#mask-a-custom-variable) makes sure it
+[masked](../ci/variables/README.md#mask-a-cicd-variable) makes sure it
 doesn't show up in the job logs. The variable cannot be
-[protected](../ci/variables/README.md#protect-a-custom-variable), as it needs
+[protected](../ci/variables/README.md#protect-a-cicd-variable), as it needs
 to be present for all feature branches.

doc/user/application_security/api_fuzzing/index.md

@@ -443,7 +443,7 @@ To use HTTP basic authentication, two CI/CD variables are added to your `.gitlab
 - `FUZZAPI_HTTP_USERNAME`: The username for authentication.
 - `FUZZAPI_HTTP_PASSWORD`: The password for authentication.
 
-For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui)
+For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#custom-cicd-variables)
 (for example, `TEST_API_PASSWORD`) set to the password. You can create CI/CD variables from the
 GitLab projects page at **Settings > CI/CD**, in the **Variables** section. Use that variable
 as the value for `FUZZAPI_HTTP_PASSWORD`:
@@ -478,7 +478,7 @@ outgoing HTTP requests.
 
 Follow these steps to provide the bearer token with `FUZZAPI_OVERRIDES_ENV`:
 
-1. [Create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui),
+1. [Create a CI/CD variable](../../../ci/variables/README.md#custom-cicd-variables),
    for example `TEST_API_BEARERAUTH`, with the value
    `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You
    can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the
@@ -817,7 +817,7 @@ variables:
 ```
 
 In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a
-[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-level-cicd-variables):
+[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-cicd-variables):
 
 ```yaml
 include:

doc/user/application_security/container_scanning/index.md

@@ -241,7 +241,7 @@ container_scanning:
         -----END CERTIFICATE-----
 ```
 
-The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
+The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
 
 ### Vulnerability allowlisting
 

doc/user/application_security/dast/index.md

@@ -271,7 +271,7 @@ that you periodically confirm the scanner's authentication is still working as t
 time due to authentication changes to the application.
 
 Create masked CI/CD variables to pass the credentials that DAST uses.
-To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui).
+To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables).
 Note that the key of the username variable must be `DAST_USERNAME`
 and the key of the password variable must be `DAST_PASSWORD`.
 

doc/user/application_security/dependency_scanning/index.md

@@ -215,7 +215,7 @@ variables:
       -----END CERTIFICATE-----
 ```
 
-The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
+The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
 
 ### Using private Maven repositories
 

doc/user/application_security/index.md

@@ -407,7 +407,7 @@ to pass a username and password. You can set it under your project's settings
 so that your credentials aren't exposed in `.gitlab-ci.yml`.
 
 If the username is `myuser` and the password is `verysecret` then you would
-[set the following variable](../../ci/variables/README.md#create-a-custom-variable-in-the-ui)
+[set the following variable](../../ci/variables/README.md#custom-cicd-variables)
 under your project's settings:
 
 | Type     | Key              | Value |

doc/user/application_security/sast/index.md

@@ -444,7 +444,7 @@ variables:
       -----END CERTIFICATE-----
 ```
 
-The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
+The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.
 
 #### Docker images
 

doc/user/compliance/license_compliance/index.md

@@ -490,7 +490,7 @@ example:
 }
 ```
 
-If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/README.md#protect-a-custom-variable)
+If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/README.md#protect-a-cicd-variable)
 following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name).
 
 #### Custom root certificates for Conan

doc/user/gitlab_com/index.md

@@ -205,7 +205,7 @@ can be used for:
 - Downloading assets from a CDN
 - Any other commands that must run before the `git init`
 
-To use this feature, define a [CI/CD variable](../../ci/variables/README.md#create-a-custom-variable-in-the-ui) called
+To use this feature, define a [CI/CD variable](../../ci/variables/README.md#custom-cicd-variables) called
 `CI_PRE_CLONE_SCRIPT` that contains a bash script.
 
 [This example](../../development/pipelines.md#pre-clone-step)

doc/user/project/clusters/serverless/aws.md

@@ -134,7 +134,7 @@ This example code does the following:
 #### Setting up your AWS credentials with your GitLab account
 
 In order to interact with your AWS account, the GitLab CI/CD pipelines require both `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be defined in your GitLab settings under **Settings > CI/CD > Variables**.
-For more information please see [Create a custom variable in the UI](../../../../ci/variables/README.md#create-a-custom-variable-in-the-ui).
+For more information please see [Create a custom variable in the UI](../../../../ci/variables/README.md#custom-variables-validated-by-gitlab).
 
  The AWS credentials you provide must include IAM policies that provision correct
  access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources.

doc/user/project/merge_requests/code_quality.md

@@ -242,8 +242,7 @@ to learn more about how to define one.
 To disable the `code_quality` job, add `CODE_QUALITY_DISABLED` as a custom CI/CD variable.
 This can be done:
 
-- For the whole project, [in the project settings](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui)
-  or [CI/CD configuration](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui).
+- For [the whole project](../../../ci/variables/README.md#custom-cicd-variables).
 - For a single pipeline run:
 
   1. Go to **CI/CD > Pipelines**