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

Update half the artifacts keywords to reference style

See merge request gitlab-org/gitlab!74977

doc/ci/pipelines/job_artifacts.md

@@ -50,6 +50,109 @@ 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).
 
+### Use CI/CD variables to define the artifacts name
+
+You can use [CI/CD variables](../variables/index.md) to dynamically define the
+artifacts file's name.
+
+For example, to create an archive with a name of the current job:
+
+```yaml
+job:
+  artifacts:
+    name: "$CI_JOB_NAME"
+    paths:
+      - binaries/
+```
+
+To create an archive with a name of the current branch or tag including only
+the binaries directory:
+
+```yaml
+job:
+  artifacts:
+    name: "$CI_COMMIT_REF_NAME"
+    paths:
+      - 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:
+
+```yaml
+job:
+  artifacts:
+    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
+    paths:
+      - binaries/
+```
+
+To create an archive with a name of the current [stage](../yaml/index.md#stages) and branch name:
+
+```yaml
+job:
+  artifacts:
+    name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
+    paths:
+      - binaries/
+```
+
+If you use **Windows Batch** to run your shell scripts you must replace
+`$` with `%`:
+
+```yaml
+job:
+  artifacts:
+    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
+    paths:
+      - binaries/
+```
+
+If you use **Windows PowerShell** to run your shell scripts you must replace
+`$` with `$env:`:
+
+```yaml
+job:
+  artifacts:
+    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
+    paths:
+      - binaries/
+```
+
+### Exclude files from job artifacts
+
+Use [`artifacts:exclude`](../yaml/index.md#artifactsexclude) to prevent files from
+being added to an artifacts archive.
+
+For example, to store all files in `binaries/`, but not `*.o` files located in
+subdirectories of `binaries/`.
+
+```yaml
+artifacts:
+  paths:
+    - binaries/
+  exclude:
+    - binaries/**/*.o
+```
+
+Unlike [`artifacts:paths`](../yaml/index.md#artifactspaths), `exclude` paths are not recursive.
+To exclude all of the contents of a directory, match them explicitly rather
+than matching the directory itself.
+
+For example, to store all files in `binaries/` but nothing located in the `temp/` subdirectory:
+
+```yaml
+artifacts:
+  paths:
+    - binaries/
+  exclude:
+    - binaries/temp/**/*
+```
+
 ## Download job artifacts
 
 You can download job artifacts or view the job archive:
@@ -103,6 +206,35 @@ To delete a job:
 1. On the top right of the job's log, select **Erase job log** (**{remove}**).
 1. On the confirmation dialog, select **OK**.
 
+## Expose job artifacts in the merge request UI
+
+Use the [`artifacts:expose_as`](../yaml/index.md#artifactsexpose_as) keyword to expose
+[job artifacts](../pipelines/job_artifacts.md) in the [merge request](../../user/project/merge_requests/index.md) UI.
+
+For example, to match a single file:
+
+```yaml
+test:
+  script: ["echo 'test' > file.txt"]
+  artifacts:
+    expose_as: 'artifact 1'
+    paths: ['file.txt']
+```
+
+With this configuration, GitLab adds a link **artifact 1** to the relevant merge request
+that points to `file1.txt`. To access the link, select **View exposed artifact**
+below the pipeline graph in the merge request overview.
+
+An example that matches an entire directory:
+
+```yaml
+test:
+  script: ["mkdir test && echo 'test' > test/file.txt"]
+  artifacts:
+    expose_as: 'artifact 1'
+    paths: ['test/']
+```
+
 ## Retrieve job artifacts for other projects
 
 To retrieve a job artifact from a different project, you might need to use a

doc/ci/yaml/index.md

@@ -628,12 +628,13 @@ test_job_2:
 
 ### `artifacts`
 
-Use `artifacts` to specify a list of files and directories that are
+Use `artifacts` to specify which files to save as [job artifacts](../pipelines/job_artifacts.md).
+Job artifacts are a list of files and directories that are
 attached to the job when it [succeeds, fails, or always](#artifactswhen).
 
 The artifacts are sent to GitLab after the job finishes. They are
-available for download in the GitLab UI if the size is not
-larger than the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd).
+available for download in the GitLab UI if the size is smaller than the
+the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd).
 
 By default, jobs in later stages automatically download all the artifacts created
 by jobs in earlier stages. You can control artifact download behavior in jobs with
@@ -652,16 +653,18 @@ artifacts are restored after [caches](#cache).
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15122) in GitLab 13.1
 > - Requires GitLab Runner 13.1
 
-`exclude` makes it possible to prevent files from being added to an artifacts
-archive.
+Use `artifacts:exclude` to prevent files from being added to an artifacts archive.
 
-Similar to [`artifacts:paths`](#artifactspaths), `exclude` paths are relative
-to the project directory. You can use Wildcards that use
-[glob](https://en.wikipedia.org/wiki/Glob_(programming)) or
-[`doublestar.PathMatch`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#PathMatch) patterns.
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
+
+**Possible inputs**:
+
+- An array of file paths, relative to the project directory.
+- You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) or
+  [`doublestar.PathMatch`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#PathMatch) patterns.
 
-For example, to store all files in `binaries/`, but not `*.o` files located in
-subdirectories of `binaries/`:
+**Example of `artifacts:exclude`**:
 
 ```yaml
 artifacts:
@@ -671,20 +674,18 @@ artifacts:
     - binaries/**/*.o
 ```
 
-Unlike [`artifacts:paths`](#artifactspaths), `exclude` paths are not recursive. To exclude all of the contents of a directory, you can match them explicitly rather than matching the directory itself.
+This example stores all files in `binaries/`, but not `*.o` files located in
+subdirectories of `binaries/`.
 
-For example, to store all files in `binaries/` but nothing located in the `temp/` subdirectory:
+**Additional details**:
 
-```yaml
-artifacts:
-  paths:
-    - binaries/
-  exclude:
-    - binaries/temp/**/*
-```
+- `artifacts:exclude` paths are not searched recursively.
+- Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded using
+  `artifacts:exclude` too.
+
+**Related topics**:
 
-Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded using
-`artifacts:exclude` too.
+- [Exclude files from job artifacts](../pipelines/job_artifacts.md#exclude-files-from-job-artifacts)
 
 #### `artifacts:expire_in`
 
@@ -704,8 +705,14 @@ they expire and are deleted. The `expire_in` setting does not affect:
   pipeline artifacts. See [When pipeline artifacts are deleted](../pipelines/pipeline_artifacts.md#when-pipeline-artifacts-are-deleted)
   for more information.
 
-The value of `expire_in` is an elapsed time in seconds, unless a unit is provided. Valid values
-include:
+After their expiry, artifacts are deleted hourly by default (using a cron job), and are not
+accessible anymore.
+
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
+
+**Possible inputs**: The expiry time. If no unit is provided, the time is in seconds.
+Valid values include:
 
 - `'42'`
 - `42 seconds`
@@ -717,7 +724,7 @@ include:
 - `3 weeks and 2 days`
 - `never`
 
-To expire artifacts one week after being uploaded:
+**Example of `artifacts:expire_in`**:
 
 ```yaml
 job:
@@ -725,139 +732,84 @@ job:
     expire_in: 1 week
 ```
 
-The expiration time period begins when the artifact is uploaded and stored on GitLab. If the expiry
-time is not defined, it defaults to the
-[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration)
-(30 days by default).
-
-To override the expiration date and protect artifacts from being automatically deleted:
-
-- Select **Keep** on the job page.
-- [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22761), set the value of
-  `expire_in` to `never`.
+**Additional details**:
 
-After their expiry, artifacts are deleted hourly by default (using a cron job), and are not
-accessible anymore.
+- The expiration time period begins when the artifact is uploaded and stored on GitLab.
+  If the expiry time is not defined, it defaults to the [instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration).
+- To override the expiration date and protect artifacts from being automatically deleted:
+  - Select **Keep** on the job page.
+  - [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22761), set the value of
+    `expire_in` to `never`.
 
 #### `artifacts:expose_as`
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) in GitLab 12.5.
 
-Use the `expose_as` keyword to expose [job artifacts](../pipelines/job_artifacts.md)
-in the [merge request](../../user/project/merge_requests/index.md) UI.
+Use the `artifacts:expose_as` keyword to
+[expose job artifacts in the merge request UI](../pipelines/job_artifacts.md#expose-job-artifacts-in-the-merge-request-ui).
 
-For example, to match a single file:
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
-```yaml
-test:
-  script: ["echo 'test' > file.txt"]
-  artifacts:
-    expose_as: 'artifact 1'
-    paths: ['file.txt']
-```
+**Possible inputs**:
 
-With this configuration, GitLab adds a link **artifact 1** to the relevant merge request
-that points to `file1.txt`. To access the link, select **View exposed artifact**
-below the pipeline graph in the merge request overview.
+- The name to display in the merge request UI for the artifacts download link.
+  Must be combined with [`artifacts:paths`](#artifactspaths).
 
-An example that matches an entire directory:
+**Example of `artifacts:expose_as`**:
 
 ```yaml
 test:
-  script: ["mkdir test && echo 'test' > test/file.txt"]
+  script: ["echo 'test' > file.txt"]
   artifacts:
     expose_as: 'artifact 1'
-    paths: ['test/']
+    paths: ['file.txt']
 ```
 
-Note the following:
+**Additional details**:
 
-- Artifacts do not display in the merge request UI when using variables to define the `artifacts:paths`.
+- If `artifacts:paths` uses [CI/CD variables](../variables/index.md), the artifacts do not display in the UI.
 - A maximum of 10 job artifacts per merge request can be exposed.
 - Glob patterns are unsupported.
-- If a directory is specified, the link is to the job [artifacts browser](../pipelines/job_artifacts.md#download-job-artifacts) if there is more than
-  one file in the directory.
-- For exposed single file artifacts with `.html`, `.htm`, `.txt`, `.json`, `.xml`,
-  and `.log` extensions, if [GitLab Pages](../../administration/pages/index.md) is:
-  - Enabled, GitLab automatically renders the artifact.
-  - Not enabled, the file is displayed in the artifacts browser.
+- If a directory is specified and there is more than one file in the directory,
+  the link is to the job [artifacts browser](../pipelines/job_artifacts.md#download-job-artifacts).
+- If [GitLab Pages](../../administration/pages/index.md) is enabled, GitLab automatically
+  renders the artifacts when the artifacts is a single file with one of these extensions:
+  - `.html` or `.htm`
+  - `.txt`
+  - `.json`
+  - `.xml`
+  - `.log`
 
 #### `artifacts:name`
 
-Use the `name` directive to define the name of the created artifacts
-archive. You can specify a unique name for every archive. The `artifacts:name`
-variable can make use of any of the [predefined variables](../variables/index.md).
-The default name is `artifacts`, which becomes `artifacts.zip` when you download it.
+Use the `artifacts:name` keyword to define the name of the created artifacts
+archive. You can specify a unique name for every archive.
 
-To create an archive with a name of the current job:
+If not defined, the default name is `artifacts`, which becomes `artifacts.zip` when downloaded.
 
-```yaml
-job:
-  artifacts:
-    name: "$CI_JOB_NAME"
-    paths:
-      - binaries/
-```
-
-To create an archive with a name of the current branch or tag including only
-the binaries directory:
-
-```yaml
-job:
-  artifacts:
-    name: "$CI_COMMIT_REF_NAME"
-    paths:
-      - 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:
-
-```yaml
-job:
-  artifacts:
-    name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
-    paths:
-      - binaries/
-```
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#default).
 
-To create an archive with a name of the current [stage](#stages) and branch name:
+**Possible inputs**:
 
-```yaml
-job:
-  artifacts:
-    name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME"
-    paths:
-      - binaries/
-```
+- The name of the artifacts archive. Can use [CI/CD variables](../variables/index.md).
 
----
+**Example of `artifacts:name`**:
 
-If you use **Windows Batch** to run your shell scripts you must replace
-`$` with `%`:
+To create an archive with a name of the current job:
 
 ```yaml
 job:
   artifacts:
-    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
+    name: "job1-artifacts-file"
     paths:
       - binaries/
 ```
 
-If you use **Windows PowerShell** to run your shell scripts you must replace
-`$` with `$env:`:
+**Related topics**:
 
-```yaml
-job:
-  artifacts:
-    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
-    paths:
-      - binaries/
-```
+- [Use CI/CD variables to define the artifacts name.](../pipelines/job_artifacts.md#use-cicd-variables-to-define-the-artifacts-name)
 
 #### `artifacts:paths`