Merge branch 'docs-artifacts-keyword-2' into 'master'

Update style of other half of artifacts subkeys

See merge request gitlab-org/gitlab!75219

doc/ci/pipelines/job_artifacts.md

@@ -48,7 +48,45 @@ is used.
 If you run two types of pipelines (like branch and scheduled) for the same ref,
 the pipeline that finishes later creates the job artifact.
 
-For more examples, view the [keyword reference for the `.gitlab-ci.yml` file](../yaml/index.md#artifacts).
+To disable artifact passing, define the job with empty [dependencies](../yaml/index.md#dependencies):
+
+```yaml
+job:
+  stage: build
+  script: make build
+  dependencies: []
+```
+
+You may want to create artifacts only for tagged releases to avoid filling the
+build server storage with temporary build artifacts. For example, use [`rules`](../yaml/index.md#rules)
+to create artifacts only for tags:
+
+```yaml
+default-job:
+  script:
+    - mvn test -U
+  rules:
+    - if: $CI_COMMIT_BRANCH
+
+release-job:
+  script:
+    - mvn package -U
+  artifacts:
+    paths:
+      - target/*.war
+  rules:
+    - if: $CI_COMMIT_TAG
+```
+
+You can use wildcards for directories too. For example, if you want to get all the
+files inside the directories that end with `xyz`:
+
+```yaml
+job:
+  artifacts:
+    paths:
+      - path/*xyz/*
+```
 
 ### Use CI/CD variables to define the artifacts name
 
@@ -153,6 +191,29 @@ artifacts:
     - binaries/temp/**/*
 ```
 
+### Add untracked files to artifacts
+
+Use [`artifacts:untracked`](../yaml/index.md#artifactsuntracked) to add all Git untracked
+files as artifacts (along with the paths defined in [`artifacts:paths`](../yaml/index.md#artifactspaths)).
+
+Save all Git untracked files and files in `binaries`:
+
+```yaml
+artifacts:
+  untracked: true
+  paths:
+    - binaries/
+```
+
+Save all untracked files but [exclude](../yaml/index.md#artifactsexclude) `*.txt`:
+
+```yaml
+artifacts:
+  untracked: true
+  exclude:
+    - "*.txt"
+```
+
 ## Download job artifacts
 
 You can download job artifacts or view the job archive:

doc/ci/yaml/index.md

@@ -819,63 +819,41 @@ job:
 #### `artifacts:paths`
 
 Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly
-link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming))
-patterns and:
+link outside it.
 
-- In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620),
-  [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match).
-- In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match).
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
-To restrict which jobs a specific job fetches artifacts from, see [dependencies](#dependencies).
+**Possible inputs**:
 
-Send all files in `binaries` and `.config`:
+- An array of file paths, relative to the project directory.
+- You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming))
+  patterns and:
+  - In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620),
+    [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match).
+  - In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match).
+
+**Example of `artifacts:paths`**:
 
 ```yaml
-artifacts:
+job:
+  artifacts:
     paths:
       - binaries/
       - .config
 ```
 
-To disable artifact passing, define the job with empty [dependencies](#dependencies):
-
-```yaml
-job:
-  stage: build
-  script: make build
-  dependencies: []
-```
-
-You may want to create artifacts only for tagged releases to avoid filling the
-build server storage with temporary build artifacts.
-
-Create artifacts only for tags (`default-job` doesn't create artifacts):
+This example creates an artifact with `.config` and all the files in the `binaries` directory.
 
-```yaml
-default-job:
-  script:
-    - mvn test -U
-  rules:
-    - if: $CI_COMMIT_BRANCH
+**Additional details**:
 
-release-job:
-  script:
-    - mvn package -U
-  artifacts:
-    paths:
-      - target/*.war
-  rules:
-    - if: $CI_COMMIT_TAG
-```
+- If not used with [`artifacts:name`](#artifactsname) defined, the artifacts file
+  is named `artifacts`, which becomes `artifacts.zip` when downloaded.
 
-You can use wildcards for directories too. For example, if you want to get all the files inside the directories that end with `xyz`:
+**Related topics**:
 
-```yaml
-job:
-  artifacts:
-    paths:
-      - path/*xyz/*
-```
+- To restrict which jobs a specific job fetches artifacts from, see [`dependencies`](#dependencies).
+- [Create job artifacts](../pipelines/job_artifacts.md#create-job-artifacts).
 
 #### `artifacts:public`
 
@@ -887,19 +865,24 @@ job:
 Use `artifacts:public` to determine whether the job artifacts should be
 publicly available.
 
-The default for `artifacts:public` is `true` which means that the artifacts in
-public pipelines are available for download by anonymous and guest users:
-
-```yaml
-artifacts:
-  public: true
-```
+When `artifacts:public` is `true` (default), the artifacts in
+public pipelines are available for download by anonymous and guest users.
 
 To deny read access for anonymous and guest users to artifacts in public
 pipelines, set `artifacts:public` to `false`:
 
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
+
+**Possible inputs**:
+
+- `true` (default if not defined) or `false`.
+
+**Example of `artifacts:paths`**:
+
 ```yaml
-artifacts:
+job:
+  artifacts:
     public: false
 ```
 
@@ -941,45 +924,44 @@ Use `artifacts:untracked` to add all Git untracked files as artifacts (along
 with the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration
 in the repository's `.gitignore` file.
 
-Send all Git untracked files:
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
-```yaml
-artifacts:
-  untracked: true
-```
+**Possible inputs**:
 
-Send all Git untracked files and files in `binaries`:
+- `true` or `false` (default if not defined).
 
-```yaml
-artifacts:
-  untracked: true
-  paths:
-    - binaries/
-```
+**Example of `artifacts:untracked`**:
 
-Send all untracked files but [exclude](#artifactsexclude) `*.txt`:
+Save all Git untracked files:
 
 ```yaml
-artifacts:
+job:
+  artifacts:
     untracked: true
-  exclude:
-    - "*.txt"
 ```
 
+**Related topics**:
+
+- [Add untracked files to artifacts](../pipelines/job_artifacts.md#add-untracked-files-to-artifacts).
+
 #### `artifacts:when`
 
 Use `artifacts:when` to upload artifacts on job failure or despite the
 failure.
 
-`artifacts:when` can be set to one of the following values:
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
+
+**Possible inputs**:
 
-1. `on_success` (default): Upload artifacts only when the job succeeds.
-1. `on_failure`: Upload artifacts only when the job fails.
-1. `always`: Always upload artifacts. For example, when
-   [uploading artifacts](../unit_test_reports.md#viewing-junit-screenshots-on-gitlab) required to
-   troubleshoot failing tests.
+- `on_success` (default): Upload artifacts only when the job succeeds.
+- `on_failure`: Upload artifacts only when the job fails.
+- `always`: Always upload artifacts. For example, when
+  [uploading artifacts](../unit_test_reports.md#viewing-junit-screenshots-on-gitlab)
+  required to troubleshoot failing tests.
 
-For example, to upload artifacts only when a job fails:
+**Example of `artifacts:when`**:
 
 ```yaml
 job: