Merge branch 'docs-yaml-notes-2' into 'master'

Adjust usage of NOTE: in CI docs (2/2)

See merge request gitlab-org/gitlab!45174

doc/ci/README.md

@@ -16,7 +16,7 @@ through the [continuous methodologies](introduction/index.md#introduction-to-cic
 - Continuous Delivery (CD)
 - Continuous Deployment (CD)
 
-NOTE: **Note:**
+TIP: **Tip:**
 Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more.
 Watch our ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/)
 webcast to learn about continuous methods and how GitLab’s built-in CI can help you simplify and scale software development.
@@ -79,7 +79,6 @@ Once you're familiar with how GitLab CI/CD works, see the
 [`.gitlab-ci.yml` full reference](yaml/README.md)
 for all the attributes you can set and use.
 
-NOTE: **Note:**
 GitLab CI/CD and [shared runners](runners/README.md#shared-runners) are enabled on GitLab.com and available for all users, limited only by the [pipeline quota](../user/gitlab_com/index.md#shared-runners).
 
 ## Concepts

doc/ci/caching/index.md

@@ -24,7 +24,6 @@ how it is defined in `.gitlab-ci.yml`.
 
 ## Cache vs artifacts
 
-NOTE: **Note:**
 Be careful if you use cache and artifacts to store the same path in your jobs
 as **caches are restored before artifacts** and the content could be overwritten.
 
@@ -73,7 +72,6 @@ Artifacts:
 - Are always uploaded to GitLab (known as coordinator).
 - Can have an expiration value for controlling disk usage (30 days by default).
 
-NOTE: **Note:**
 Both artifacts and caches define their paths relative to the project directory, and
 can't link to files outside it.
 
@@ -204,9 +202,7 @@ runs of jobs for things like dependencies and commonly used libraries
 (Node.js packages, PHP packages, rubygems, Python libraries, etc.),
 so they don't have to be re-fetched from the public internet.
 
-NOTE: **Note:**
-For more examples, check out our [GitLab CI/CD
-templates](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates).
+For more examples, check out our [GitLab CI/CD templates](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates).
 
 ### Caching Node.js dependencies
 

doc/ci/docker/using_docker_images.md

@@ -812,7 +812,6 @@ time.
 
 ## How to debug a job locally
 
-NOTE: **Note:**
 The following commands are run without root privileges. You should be
 able to run Docker with your regular user account.
 

doc/ci/enable_or_disable_ci.md

@@ -31,7 +31,6 @@ either:
 - Site-wide by modifying the settings in `gitlab.yml` and `gitlab.rb` for source
   and Omnibus installations respectively.
 
-NOTE: **Note:**
 This only applies to pipelines run as part of GitLab CI/CD. This will not enable or disable
 pipelines that are run from an [external integration](../user/project/integrations/overview.md#integrations-listing).
 

doc/ci/introduction/index.md

@@ -12,7 +12,7 @@ In this document, we'll present an overview of the concepts of Continuous Integr
 Continuous Delivery, and Continuous Deployment, as well as an introduction to
 GitLab CI/CD.
 
-NOTE: **Note:**
+TIP: **Tip:**
 Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more.
 Watch our ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/)
 webcast to learn about continuous methods and how GitLab’s built-in CI can help you simplify and scale software development.

doc/ci/multi_project_pipelines.md

@@ -213,10 +213,9 @@ In this scenario, the `UPSTREAM_BRANCH` variable with a value related to the
 upstream pipeline will be passed to the `downstream-job` job, and will be available
 within the context of all downstream builds.
 
-NOTE: **Tip:**
 Upstream pipelines take precedence over downstream ones. If there are two
 variables with the same name defined in both upstream and downstream projects,
-the ones defined in the upstream project will take precedence.
+the ones defined in the upstream project take precedence.
 
 #### With variable inheritance
 

doc/ci/parent_child_pipelines.md

@@ -83,8 +83,7 @@ microservice_a:
         file: 'path/to/ci-config.yml'
 ```
 
-NOTE: **Note:**
-The max number of entries that are accepted for `trigger:include:` is three.
+The maximum number of entries that are accepted for `trigger:include:` is three.
 
 Similar to [multi-project pipelines](multi_project_pipelines.md#mirroring-status-from-triggered-pipeline),
 we can set the parent pipeline to depend on the status of the child pipeline upon completion:

doc/ci/quick_start/README.md

@@ -68,11 +68,6 @@ blog about it](https://about.gitlab.com/blog/2015/05/06/why-were-replacing-gitla
 
 ### Creating a simple `.gitlab-ci.yml` file
 
-NOTE: **Note:**
-A GitLab team member has made an [unofficial visual pipeline editor](https://unofficial.gitlab.tools/visual-pipelines/).
-There is a [plan to make it an official part of GitLab](https://gitlab.com/groups/gitlab-org/-/epics/4069)
-in the future, but it's available for anyone who wants to try it at the above link.
-
 You need to create a file named `.gitlab-ci.yml` in the root directory of your
 repository. This is a [YAML](https://en.wikipedia.org/wiki/YAML) file
 so you have to pay extra attention to indentation. Always use spaces, not tabs.
@@ -120,6 +115,11 @@ If you want to check whether the `.gitlab-ci.yml` of your project is valid, ther
 For more information and a complete `.gitlab-ci.yml` syntax, please read
 [the reference documentation on `.gitlab-ci.yml`](../yaml/README.md).
 
+TIP: **Tip:**
+A GitLab team member has made an [unofficial visual pipeline editor](https://unofficial.gitlab.tools/visual-pipelines/).
+There is a [plan to make it an official part of GitLab](https://gitlab.com/groups/gitlab-org/-/epics/4069)
+in the future, but it's available for anyone who wants to try it at the above link.
+
 ### Push `.gitlab-ci.yml` to GitLab
 
 Once you've created `.gitlab-ci.yml`, you should add it to your Git repository

doc/ci/ssh_keys/README.md

@@ -36,7 +36,6 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/)
    `~/.ssh/authorized_keys`) or add it as a [deploy key](../../ssh/README.md#deploy-keys)
    if you are accessing a private GitLab repository.
 
-NOTE: **Note:**
 The private key will not be displayed in the job log, unless you enable
 [debug logging](../variables/README.md#debug-logging). You might also want to
 check the [visibility of your pipelines](../pipelines/settings.md#visibility-of-pipelines).
@@ -94,7 +93,6 @@ to access it. This is where an SSH key pair comes in handy.
      # - git config --global user.name "User name"
    ```
 
-   NOTE: **Note:**
    The [`before_script`](../yaml/README.md#before_script-and-after_script) can be set globally
    or per-job.
 
@@ -164,7 +162,6 @@ ssh-keyscan 1.2.3.4
 Create a new [variable](../variables/README.md#gitlab-cicd-environment-variables) with
 `SSH_KNOWN_HOSTS` as "Key", and as a "Value" add the output of `ssh-keyscan`.
 
-NOTE: **Note:**
 If you need to connect to multiple servers, all the server host keys
 need to be collected in the **Value** of the variable, one key per line.
 

doc/ci/triggers/README.md

@@ -252,10 +252,6 @@ of all types of variables.
 
 ## Using cron to trigger nightly pipelines
 
-NOTE: **Note:**
-The following behavior can also be achieved through GitLab's UI with
-[pipeline schedules](../pipelines/schedules.md).
-
 Whether you craft a script or just run cURL directly, you can trigger jobs
 in conjunction with cron. The example below triggers a job on the `master`
 branch of project with ID `9` every night at `00:30`:
@@ -264,6 +260,9 @@ branch of project with ID `9` every night at `00:30`:
 30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline
 ```
 
+This behavior can also be achieved through GitLab's UI with
+[pipeline schedules](../pipelines/schedules.md).
+
 ## Legacy triggers
 
 Old triggers, created before GitLab 9.0 are marked as legacy.

doc/ci/unit_test_reports.md

@@ -82,7 +82,6 @@ To make the Unit test report output files browsable, include them with the
 To upload the report even if the job fails (for example if the tests do not pass), use the [`artifacts:when:always`](yaml/README.md#artifactswhen)
 keyword.
 
-NOTE: **Note:**
 You cannot have multiple tests with the same name and class in your JUnit report format XML file.
 
 ### Ruby example
@@ -144,8 +143,8 @@ java:
       junit: build/test-results/test/**/TEST-*.xml
 ```
 
-NOTE: **Note:**
-Support for `**` was added in [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620).
+In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620)
+and later, you can use `**`.
 
 #### Maven
 

doc/ci/yaml/README.md

@@ -399,6 +399,10 @@ configuration files. This helps avoid duplicated configuration, for example, glo
 `include` requires the external YAML file to have the extensions `.yml` or `.yaml`,
 otherwise the external file is not included.
 
+Using [YAML anchors](#anchors) across different YAML files sourced by `include` is not
+supported. You must only refer to anchors in the same file. Instead
+of using YAML anchors, you can use the [`extends` keyword](#extends).
+
 `include` supports the following inclusion methods:
 
 | Method                          | Description                                                       |
@@ -410,7 +414,6 @@ otherwise the external file is not included.
 
 The `include` methods do not support [variable expansion](../variables/where_variables_can_be_used.md#variables-usage).
 
-NOTE: **Note:**
 `.gitlab-ci.yml` configuration included by all methods is evaluated at pipeline creation.
 The configuration is a snapshot in time and persisted in the database. Any changes to
 referenced `.gitlab-ci.yml` configuration is not reflected in GitLab until the next pipeline is created.
@@ -425,11 +428,6 @@ TIP: **Tip:**
 Use merging to customize and override included CI/CD configurations with local
 definitions. Local definitions in `.gitlab-ci.yml` override included definitions.
 
-NOTE: **Note:**
-Using [YAML anchors](#anchors) across different YAML files sourced by `include` is not
-supported. You must only refer to anchors in the same file. Instead
-of using YAML anchors, you can use the [`extends` keyword](#extends).
-
 #### `include:local`
 
 `include:local` includes a file from the same repository as `.gitlab-ci.yml`.
@@ -439,12 +437,11 @@ You can only use files that are tracked by Git on the same branch
 your configuration file is on. In other words, when using a `include:local`, make
 sure that both `.gitlab-ci.yml` and the local file are on the same branch.
 
+Including local files through Git submodules paths is not supported.
+
 All [nested includes](#nested-includes) are executed in the scope of the same project,
 so it's possible to use local, project, remote, or template includes.
 
-NOTE: **Note:**
-Including local files through Git submodules paths is not supported.
-
 Example:
 
 ```yaml
@@ -452,7 +449,6 @@ include:
   - local: '/templates/.gitlab-ci-template.yml'
 ```
 
-TIP: **Tip:**
 Local includes can be used as a replacement for symbolic links that are not followed.
 
 This can be defined as a short local include:
@@ -891,6 +887,8 @@ The following stages are available to every pipeline:
 
 User-defined stages are executed after `.pre` and before `.post`.
 
+A pipeline is not created if all jobs are in `.pre` or `.post` stages.
+
 The order of `.pre` and `.post` can't be changed, even if defined out of order in `.gitlab-ci.yml`.
 For example, the following are equivalent configuration:
 
@@ -922,9 +920,6 @@ For example, the following are equivalent configuration:
     - b
   ```
 
-NOTE: **Note:**
-A pipeline is not created if all jobs are in `.pre` or `.post` stages.
-
 ### `extends`
 
 > Introduced in GitLab 11.3.
@@ -1106,7 +1101,6 @@ is either included or excluded from the pipeline, depending on the configuration
 If included, the job also has [certain attributes](#rules-attributes)
 added to it.
 
-CAUTION: **Caution:**
 `rules` replaces [`only/except`](#onlyexcept-basic) and can't be used in conjunction with it.
 If you attempt to use both keywords in the same job, the linter returns a
 `key may not be used with rules` error.
@@ -1560,7 +1554,7 @@ job1:
     if: ($CI_COMMIT_BRANCH == "master" || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE
 ```
 
-NOTE: **Note:**
+CAUTION: **Caution:**
 [Before GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/230938),
 rules that use both `||` and `&&` may evaluate with an unexpected order of operations.
 
@@ -1716,10 +1710,6 @@ Feature.enable(:allow_unsafe_ruby_regexp)
 
 ### `only`/`except` (advanced)
 
-CAUTION: **Warning:**
-This is an _alpha_ feature, and is subject to change at any time without
-prior notice!
-
 GitLab supports both simple and complex strategies, so it's possible to use an
 array and a hash configuration scheme.
 
@@ -2726,10 +2716,6 @@ as Review Apps. You can see a simple example using Review Apps at
 >   by default.
 > - From GitLab 9.2, caches are restored before [artifacts](#artifacts).
 
-TIP: **Learn more:**
-Read how caching works and find out some good practices in the
-[caching dependencies documentation](../caching/index.md).
-
 `cache` is used to specify a list of files and directories that should be
 cached between jobs. You can only use paths that are within the local working
 copy.
@@ -2737,6 +2723,9 @@ copy.
 If `cache` is defined outside the scope of jobs, it means it's set
 globally and all jobs use that definition.
 
+Read how caching works and find out some good practices in the
+[caching dependencies documentation](../caching/index.md).
+
 #### `cache:paths`
 
 Use the `paths` directive to choose which files or directories to cache. Paths
@@ -2798,10 +2787,6 @@ The `cache:key` variable can use any of the
 set, is just literal `default`, which means everything is shared between
 pipelines and jobs by default, starting from GitLab 9.0.
 
-NOTE: **Note:**
-The `cache:key` variable can't contain the `/` character, or the equivalent
-URI-encoded `%2F`; a value made only of dots (`.`, `%2E`) is also forbidden.
-
 For example, to enable per-branch caching:
 
 ```yaml
@@ -2821,6 +2806,9 @@ cache:
     - binaries/
 ```
 
+The `cache:key` variable can't contain the `/` character, or the equivalent
+URI-encoded `%2F`. A value made only of dots (`.`, `%2E`) is also forbidden.
+
 You can specify a [fallback cache key](#fallback-cache-key) to use if the specified `cache:key` is not found.
 
 ##### `cache:key:files`
@@ -3141,11 +3129,6 @@ useful when you want to download the archive from GitLab. The `artifacts:name`
 variable can make use of any of the [predefined variables](../variables/README.md).
 The default name is `artifacts`, which becomes `artifacts.zip` when you download it.
 
-NOTE: **Note:**
-If your branch-name contains forward slashes
-(for example `feature/my-feature`) it's advised to use `$CI_COMMIT_REF_SLUG`
-instead of `$CI_COMMIT_REF_NAME` for proper naming of the artifact.
-
 To create an archive with a name of the current job:
 
 ```yaml
@@ -3167,6 +3150,10 @@ job:
       - binaries/
 ```
 
+If your branch-name contains forward slashes
+(for example `feature/my-feature`) it's advised to use `$CI_COMMIT_REF_SLUG`
+instead of `$CI_COMMIT_REF_NAME` for proper naming of the artifact.
+
 To create an archive with a name of the current job and the current branch or
 tag including only the binaries directory:
 
@@ -3215,10 +3202,8 @@ job:
 #### `artifacts:untracked`
 
 `artifacts:untracked` is used to add all Git untracked files as artifacts (along
-to the paths defined in `artifacts:paths`).
-
-NOTE: **Note:**
-`artifacts:untracked` ignores configuration in the repository's `.gitignore` file.
+to the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration
+in the repository's `.gitignore` file.
 
 Send all Git untracked files:
 
@@ -3308,7 +3293,6 @@ job:
     expire_in: 1 week
 ```
 
-NOTE: **Note:**
 The latest artifacts for refs are locked against deletion, and kept regardless of
 the expiry time. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/16267)
 GitLab 13.0 behind a disabled feature flag, and [made the default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936)
@@ -3407,7 +3391,6 @@ If the artifacts of the job that is set as a dependency have been
 [erased](../pipelines/job_artifacts.md#erasing-artifacts), then
 the dependent job fails.
 
-NOTE: **Note:**
 You can ask your administrator to
 [flip this switch](../../administration/job_artifacts.md#validation-for-dependencies)
 and bring back the old behavior.
@@ -3554,7 +3537,6 @@ test:
   parallel: 5
 ```
 
-TIP: **Tip:**
 Parallelize tests suites across parallel jobs.
 Different languages have different tools to facilitate this.
 
@@ -3811,11 +3793,10 @@ When enabled, a pipeline on the same branch is canceled when:
 - It's made redundant by a newer pipeline run.
 - Either all jobs are set as interruptible, or any uninterruptible jobs haven't started.
 
-Pending jobs are always considered interruptible.
-
-TIP: **Tip:**
 Set jobs as interruptible that can be safely canceled once started (for instance, a build job).
 
+Pending jobs are always considered interruptible.
+
 Here is a simple example:
 
 ```yaml
@@ -3847,7 +3828,6 @@ In the example above, a new pipeline run causes an existing running pipeline to
 - Canceled, if only `step-1` is running or pending.
 - Not canceled, once `step-2` starts running.
 
-NOTE: **Note:**
 When an uninterruptible job is running, the pipeline can never be canceled, regardless of the final job's state.
 
 ### `resource_group`
@@ -3879,11 +3859,10 @@ In this case, two `deploy-to-production` jobs in two separate pipelines can neve
 you can ensure that concurrent deployments never happen to the production environment.
 
 There can be multiple `resource_group`s defined per environment. A good use case for this
-is when deploying to physical devices. You may have more than one physical device, and each
-one can be deployed to, but there can be only one deployment per device at any given time.
+is when deploying to physical devices. You may have multiple physical devices that
+can be deployed to, but there can be only one deployment per device at any given time.
 
-NOTE: **Note:**
-This key can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces.
+The `resource_group` value can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces.
 It can't start or end with `/`.
 
 For more information, see [Deployments Safety](../environments/deployment_safety.md).
@@ -4478,11 +4457,6 @@ You can set it globally or per-job in the [`variables`](#variables) section.
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2211) in GitLab Runner 11.10.
 
-NOTE: **Note:**
-This can only be used when `custom_build_dir` is enabled in the [runner's
-configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section).
-This is the default configuration for `docker` and `kubernetes` executor.
-
 By default, GitLab Runner clones the repository in a unique subpath of the
 `$CI_BUILDS_DIR` directory. However, your project might require the code in a
 specific directory (Go projects, for example). In that case, you can specify
@@ -4502,6 +4476,10 @@ The `GIT_CLONE_PATH` has to always be within `$CI_BUILDS_DIR`. The directory set
 is dependent on executor and configuration of [runners.builds_dir](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section)
 setting.
 
+This can only be used when `custom_build_dir` is enabled in the
+[runner's configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section).
+This is the default configuration for the `docker` and `kubernetes` executors.
+
 #### Handling concurrency
 
 An executor that uses a concurrency greater than `1` might lead
@@ -4582,6 +4560,10 @@ Use anchors to duplicate or inherit properties. Use anchors with [hidden jobs](#
 to provide templates for your jobs. When there are duplicate keys, GitLab
 performs a reverse deep merge based on the keys.
 
+You can't use YAML anchors across multiple files when leveraging the [`include`](#include)
+feature. Anchors are only valid within the file they were defined in. Instead
+of using YAML anchors, you can use the [`extends` keyword](#extends).
+
 The following example uses anchors and map merging. It creates two jobs,
 `test1` and `test2`, that inherit the parameters of `.job_template`, each
 with their own custom `script` defined:
@@ -4703,15 +4685,8 @@ test:mysql:
     - dev
 ```
 
-You can see that the hidden jobs are conveniently used as templates.
-
-NOTE: **Note:**
-Note that `tags: [dev]` has been overwritten by `tags: [postgres]`.
-
-NOTE: **Note:**
-You can't use YAML anchors across multiple files when leveraging the [`include`](#include)
-feature. Anchors are only valid within the file they were defined in. Instead
-of using YAML anchors, you can use the [`extends` keyword](#extends).
+You can see that the hidden jobs are conveniently used as templates, and
+`tags: [dev]` has been overwritten by `tags: [postgres]`.
 
 #### YAML anchors for `before_script` and `after_script`