Edited for style

Related to: https://gitlab.com/gitlab-org/gitlab/-/issues/300312

doc/administration/job_artifacts.md

@@ -89,7 +89,7 @@ _The artifacts are stored by default in
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1762) in
 >   [GitLab Premium](https://about.gitlab.com/pricing/) 9.4.
-> - Since version 9.5, artifacts are [browsable](../ci/pipelines/job_artifacts.md#browsing-artifacts),
+> - Since version 9.5, artifacts are [browsable](../ci/pipelines/job_artifacts.md#download-job-artifacts),
 >   when object storage is enabled. 9.4 lacks this feature.
 > - Since version 10.6, available in [GitLab Free](https://about.gitlab.com/pricing/).
 > - Since version 11.0, we support `direct_upload` to S3.
@@ -509,7 +509,7 @@ If you need to manually remove job artifacts associated with multiple jobs while
 
    NOTE:
    This step also erases artifacts that users have chosen to
-   ["keep"](../ci/pipelines/job_artifacts.md#browsing-artifacts).
+   ["keep"](../ci/pipelines/job_artifacts.md#download-job-artifacts).
 
    ```ruby
    builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago)

doc/administration/pages/index.md

@@ -487,7 +487,7 @@ internet connectivity is gated by a proxy. To use a proxy for GitLab Pages:
 ### Using a custom Certificate Authority (CA)
 
 When using certificates issued by a custom CA, [Access Control](../../user/project/pages/pages_access_control.md#gitlab-pages-access-control) and
-the [online view of HTML job artifacts](../../ci/pipelines/job_artifacts.md#browsing-artifacts)
+the [online view of HTML job artifacts](../../ci/pipelines/job_artifacts.md#download-job-artifacts)
 fails to work if the custom CA is not recognized.
 
 This usually results in this error:

doc/ci/pipelines/job_artifacts.md

@@ -8,25 +8,19 @@ type: reference, howto
 
 # Job artifacts
 
-> - Introduced in GitLab 8.2 and GitLab Runner 0.7.0.
-> - Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format changed to `ZIP`, and it's now possible to browse its contents, with the added ability of downloading the files separately.
-> - In GitLab 8.17, builds were renamed to jobs.
-> - The artifacts browser is available only for new artifacts that are sent to GitLab using GitLab Runner version 1.0 and up. You cannot browse old artifacts already uploaded to GitLab.
+> Introduced in [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16675), artifacts in internal and private projects can be previewed when [GitLab Pages access control](../../administration/pages/index.md#access-control) is enabled.
 
-Job artifacts are a list of files and directories created by a job
-once it finishes. This feature is [enabled by default](../../administration/job_artifacts.md) in all
-GitLab installations.
+Jobs can output an archive of files and directories. This output is known as a job artifact.
 
-Job artifacts created by GitLab Runner are uploaded to GitLab and are downloadable as a single archive using the GitLab UI or the [GitLab API](../../api/job_artifacts.md#get-job-artifacts).
+You can download job artifacts by using the GitLab UI or the [API](../../api/job_artifacts.md#get-job-artifacts).
 
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s).
 Watch also [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII).
 
-## Defining artifacts in `.gitlab-ci.yml`
+## Define artifacts in the `.gitlab-ci.yml` file
 
-A simple example of using the artifacts definition in `.gitlab-ci.yml` would be
-the following:
+This example shows how to configure your `.gitlab-ci.yml` file to create job artifacts:
 
 ```yaml
 pdf:
@@ -38,19 +32,169 @@ pdf:
 ```
 
 A job named `pdf` calls the `xelatex` command to build a PDF file from the
-latex source file `mycv.tex`. We then define the `artifacts` paths which in
-turn are defined with the `paths` keyword. All paths to files and directories
-are relative to the repository that was cloned during the build.
+LaTeX source file, `mycv.tex`.
 
-By default, the artifacts upload when the job succeeds. You can also set artifacts to upload
-when the job fails, or always, by using [`artifacts:when`](../yaml/README.md#artifactswhen)
-keyword. GitLab keeps these uploaded artifacts for 1 week, as defined
-by the `expire_in` definition. You can keep the artifacts from expiring
-via the [web interface](#browsing-artifacts). If the expiry time is not defined, it defaults
-to the [instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration).
+The `paths` keyword determines which files to add to the job artifacts.
+All paths to files and directories are relative to the repository where the job was created.
 
-For more examples on artifacts, follow the [artifacts reference in
-`.gitlab-ci.yml`](../yaml/README.md#artifacts).
+The `expire_in` keyword determines how long GitLab keeps the job artifacts.
+You can also [use the UI to keep job artifacts from expiring](#download-job-artifacts).
+If `expire_in` is not defined, the
+[instance-wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration)
+is used.
+
+For more examples, view the [keyword reference for the `.gitlab-ci.yml` file](../yaml/README.md#artifacts).
+
+## Download job artifacts
+
+You can download job artifacts or view the job archive:
+
+- On the **Pipelines** page, to the right of the pipeline:
+
+  ![Job artifacts in Pipelines page](img/job_artifacts_pipelines_page.png)
+
+- On the **Jobs** page, to the right of the job:
+
+  ![Job artifacts in Builds page](img/job_artifacts_builds_page.png)
+
+- On a job's detail page. The **Keep** button indicates an `expire_in` value was set:
+
+  ![Job artifacts browser button](img/job_artifacts_browser_button.png)
+
+- On a merge request, by the pipeline details:
+
+  ![Job artifacts in Merge Request](img/job_artifacts_merge_request.png)
+
+- When browsing an archive:
+
+  ![Job artifacts browser](img/job_artifacts_browser.png)
+
+  If [GitLab Pages](../../administration/pages/index.md) is enabled in the project, you can preview
+  HTML files in the artifacts directly in your browser. If the project is internal or private, you must
+  enable [GitLab Pages access control](../../administration/pages/index.md#access-control) to preview
+  HTML files.
+
+## View failed job artifacts
+
+If the latest job has failed to upload the artifacts, you can see that
+information in the UI.
+
+![Latest artifacts button](img/job_latest_artifacts_browser.png)
+
+## Erase job artifacts
+
+WARNING:
+This is a destructive action that leads to data loss. Use with caution.
+
+You can erase a single job, which also removes the job's
+artifacts and log. You must be:
+
+- The owner of the job.
+- A [Maintainer](../../user/permissions.md#gitlab-cicd-permissions) of the project.
+
+To erase a job:
+
+1. Go to a job's detail page.
+1. At the top right of the job's log, select the trash icon.
+1. Confirm the deletion.
+
+## Use GitLab CI/CD to retrieve job artifacts for private projects
+
+To retrieve a job artifact from a different project, you might need to use a
+private token to [authenticate and download](../../api/job_artifacts.md#get-job-artifacts)
+the artifact.
+
+## The latest job artifacts
+
+Job artifacts created in the most recent successful pipeline for a specific ref
+are considered the latest artifacts. If you run two types of pipelines for the same ref,
+timing determines which artifacts are the latest.
+
+For example, if a merge request creates a branch pipeline at the same time as
+a scheduled pipeline, the pipeline that finished most recently creates the latest job artifact.
+
+In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201784) and later, artifacts
+for [parent and child pipelines](../parent_child_pipelines.md) are searched in hierarchical
+order from parent to child. For example, if both parent and child pipelines have a
+job with the same name, the job artifact from the parent pipeline is returned.
+
+## Access the latest job artifacts by URL
+
+You can download the latest job artifacts by using a URL.
+
+To download the whole artifacts archive:
+
+```plaintext
+https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/download?job=<job_name>
+```
+
+To download a single file from the artifacts:
+
+```plaintext
+https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/raw/<path_to_file>?job=<job_name>
+```
+
+For example, to download the latest artifacts of the job named `coverage` of
+the `master` branch of the `gitlab` project that belongs to the `gitlab-org`
+namespace:
+
+```plaintext
+https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/download?job=coverage
+```
+
+To download the file `coverage/index.html` from the same artifacts:
+
+```plaintext
+https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/raw/coverage/index.html?job=coverage
+```
+
+To browse the latest job artifacts:
+
+```plaintext
+https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/browse?job=<job_name>
+```
+
+For example:
+
+```plaintext
+https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/browse?job=coverage
+```
+
+There is also a URL for specific files, including HTML files that
+are shown in [GitLab Pages](../../administration/pages/index.md):
+
+```plaintext
+https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/file/<path>?job=<job_name>
+```
+
+For example, when a job `coverage` creates the artifact `htmlcov/index.html`:
+
+```plaintext
+https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/file/htmlcov/index.html?job=coverage
+```
+
+### Keep artifacts from most recent successful jobs
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0.
+> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4.
+> - [Made optional with a CI/CD setting](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8.
+
+By default, the latest job artifacts from the most recent successful jobs are never deleted.
+If a job is configured with [`expire_in`](../yaml/README.md#artifactsexpire_in),
+its artifacts only expire if a more recent artifact exists.
+
+Keeping the latest artifacts can use a large amount of storage space in projects
+with a lot of jobs or large artifacts. If the latest artifacts are not needed in
+a project, you can disable this behavior to save space:
+
+1. Go to the project's **Settings > CI/CD > Artifacts**.
+1. Clear the **Keep artifacts from most recent successful jobs** checkbox.
+
+You can disable this behavior for all projects on a self-managed instance in the
+[instance's CI/CD settings](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
+
+When you disable the feature, the latest artifacts do not immediately expire.
+A new pipeline must run before the latest artifacts can expire and be deleted.
 
 ### `artifacts:reports`
 
@@ -306,191 +450,7 @@ The collected Requirements report uploads to GitLab as an artifact and
 existing [requirements](../../user/project/requirements/index.md) are
 marked as Satisfied.
 
-## Browsing artifacts
-
-> - From GitLab 9.2, PDFs, images, videos, and other formats can be previewed directly in the job artifacts browser without the need to download them.
-> - Introduced in [GitLab 10.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14399), HTML files in a public project can be previewed directly in a new tab without the need to download them when [GitLab Pages](../../administration/pages/index.md) is enabled. The same applies for textual formats (currently supported extensions: `.txt`, `.json`, and `.log`).
-> - Introduced in [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16675), artifacts in internal and private projects can be previewed when [GitLab Pages access control](../../administration/pages/index.md#access-control) is enabled.
-
-After a job finishes, if you visit the job's specific page, there are three
-buttons. You can download the artifacts archive or browse its contents, whereas
-the **Keep** button appears only if you've set an [expiry date](../yaml/README.md#artifactsexpire_in) to the
-artifacts in case you changed your mind and want to keep them.
-
-![Job artifacts browser button](img/job_artifacts_browser_button.png)
-
-The archive browser shows the name and the actual file size of each file in the
-archive. If your artifacts contained directories, then you're also able to
-browse inside them.
-
-Below you can see what browsing looks like. In this case we have browsed inside
-the archive and at this point there is one directory, a couple files, and
-one HTML file that you can view directly online when
-[GitLab Pages](../../administration/pages/index.md) is enabled (opens in a new tab).
-Select artifacts in internal and private projects can only be previewed when
-[GitLab Pages access control](../../administration/pages/index.md#access-control) is enabled.
-
-![Job artifacts browser](img/job_artifacts_browser.png)
-
-## Downloading artifacts
-
-If you need to download an artifact or the whole archive, there are buttons in various places
-in the GitLab UI to do this:
-
-1. While on the pipelines page, you can see the download icon for each job's
-   artifacts and archive in the right corner:
-
-   ![Job artifacts in Pipelines page](img/job_artifacts_pipelines_page.png)
-
-1. While on the **Jobs** page, you can see the download icon for each job's
-   artifacts and archive in the right corner:
-
-   ![Job artifacts in Builds page](img/job_artifacts_builds_page.png)
-
-1. While inside a specific job, you're presented with a download button
-   along with the one that browses the archive:
-
-   ![Job artifacts browser button](img/job_artifacts_browser_button.png)
-
-1. While on the details page of a merge request, you can see the download
-   icon for each job's artifacts on the right side of the merge request widget:
-
-   ![Job artifacts in Merge Request](img/job_artifacts_merge_request.png)
-
-1. And finally, when browsing an archive you can see the download button at
-   the top right corner:
-
-   ![Job artifacts browser](img/job_artifacts_browser.png)
-
-## Downloading the latest artifacts
-
-It's possible to download the latest artifacts of a job via a well known URL
-so you can use it for scripting purposes.
-
-NOTE:
-The latest artifacts are created by jobs in the **most recent** successful pipeline
-for the specific ref. If you run two types of pipelines for the same ref, timing determines the latest
-artifact. For example, if a merge request creates a branch pipeline at the same time as a scheduled pipeline, the pipeline that completed most recently creates the latest artifact.
-
-In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201784) and later, artifacts
-for [parent and child pipelines](../parent_child_pipelines.md) are searched in hierarchical
-order from parent to child. For example, if both parent and child pipelines have a
-job with the same name, the artifact from the parent pipeline is returned.
-
-Artifacts for other pipelines can be accessed with direct access to them.
-
-The structure of the URL to download the whole artifacts archive is the following:
-
-```plaintext
-https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/download?job=<job_name>
-```
-
-To download a single file from the artifacts use the following URL:
-
-```plaintext
-https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/raw/<path_to_file>?job=<job_name>
-```
-
-For example, to download the latest artifacts of the job named `coverage` of
-the `master` branch of the `gitlab` project that belongs to the `gitlab-org`
-namespace, the URL would be:
-
-```plaintext
-https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/download?job=coverage
-```
-
-To download the file `coverage/index.html` from the same
-artifacts use the following URL:
-
-```plaintext
-https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/raw/coverage/index.html?job=coverage
-```
-
-There is also a URL to browse the latest job artifacts:
-
-```plaintext
-https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/browse?job=<job_name>
-```
-
-For example:
-
-```plaintext
-https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/browse?job=coverage
-```
-
-There is also a URL to specific files, including HTML files that
-are shown in [GitLab Pages](../../administration/pages/index.md):
-
-```plaintext
-https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/file/<path>?job=<job_name>
-```
-
-For example, when a job `coverage` creates the artifact `htmlcov/index.html`,
-you can access it at:
-
-```plaintext
-https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/file/htmlcov/index.html?job=coverage
-```
-
-The latest builds are also exposed in the UI in various places. Specifically,
-look for the download button in:
-
-- The main project's page
-- The branches page
-- The tags page
-
-If the latest job has failed to upload the artifacts, you can see that
-information in the UI.
-
-![Latest artifacts button](img/job_latest_artifacts_browser.png)
-
-## Erasing artifacts
-
-WARNING:
-This is a destructive action that leads to data loss. Use with caution.
-
-You can erase a single job via the UI, which also removes the job's
-artifacts and trace, if you are:
-
-- The owner of the job.
-- A [Maintainer](../../user/permissions.md#gitlab-cicd-permissions) of the project.
-
-To erase a job:
-
-1. Navigate to a job's page.
-1. Click the trash icon at the top right of the job's trace.
-1. Confirm the deletion.
-
-## Retrieve artifacts of private projects when using GitLab CI
-
-To retrieve a job artifact from a different project, you might need to use a
-private token to [authenticate and download](../../api/job_artifacts.md#get-job-artifacts)
-the artifact.
-
-## Keep artifacts from most recent successful jobs
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4.
-> - [Made optional with a CI/CD setting](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8.
-
-By default, the latest artifacts from the most recent successful jobs are never deleted.
-If a job is configured with [`expire_in`](../yaml/README.md#artifactsexpire_in),
-its artifacts only expire if a more recent artifact exists.
-
-Keeping the latest artifacts can use a large amount of storage space in projects
-with a lot of jobs or large artifacts. If the latest artifacts are not needed in
-a project, you can disable this behavior to save space:
-
-1. Navigate to **Settings > CI/CD > Artifacts**.
-1. Uncheck **Keep artifacts from most recent successful jobs**.
-
-You can disable this behavior for all projects on a self-managed instance in the
-[instance's CI/CD settings](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). **(CORE ONLY)**
-
-When you disable the feature, the latest artifacts do not immediately expire.
-A new pipeline must run before the latest artifacts can expire and be deleted.
-
-## Troubleshooting
+## Troubleshooting job artifacts
 
 ### Error message `No files to upload`
 

doc/ci/yaml/README.md

@@ -3239,7 +3239,7 @@ Note the following:
 - Artifacts do not display in the merge request UI when using variables to define the `artifacts:paths`.
 - 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#browsing-artifacts) if there is more than
+- 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:
@@ -3508,7 +3508,7 @@ deploy:
 
 If the artifacts of the job that is set as a dependency are
 [expired](#artifactsexpire_in) or
-[erased](../pipelines/job_artifacts.md#erasing-artifacts), then
+[erased](../pipelines/job_artifacts.md#erase-job-artifacts), then
 the dependent job fails.
 
 You can ask your administrator to

doc/user/application_security/coverage_fuzzing/index.md

@@ -141,7 +141,7 @@ The `gitlab-cov-fuzz` tool emits a JSON report file. For more information, see t
 [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json).
 
 You can download the JSON report file from the CI pipelines page. For more information, see
-[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#downloading-artifacts).
+[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts).
 
 Here's an example coverage fuzzing report:
 

doc/user/application_security/sast/index.md

@@ -536,7 +536,7 @@ The SAST tool emits a JSON report file. For more information, see the
 [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json).
 
 The JSON report file can be downloaded from the CI pipelines page, or the
-pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/pipelines/job_artifacts.md#defining-artifacts-in-gitlab-ciyml) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md).
+pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/yaml/README.md#artifactspaths) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md).
 
 Here's an example SAST report:
 

doc/user/project/merge_requests/accessibility_testing.md

@@ -57,7 +57,7 @@ include:
 creates an `a11y` job in your CI/CD pipeline, runs
 Pa11y against the web pages defined in `a11y_urls`, and builds an HTML report for each.
 
-The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#browsing-artifacts).
+The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts).
 
 A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports.
 It includes report data for all URLs scanned.

doc/user/project/merge_requests/code_quality.md

@@ -355,7 +355,7 @@ After the Code Quality job completes:
   The Code Quality widget in the merge request compares the reports from the base and head of the branch,
   then lists any violations that are resolved or created when the branch is merged.
 - The full JSON report is available as a
-  [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts)
+  [downloadable artifact](../../../ci/pipelines/job_artifacts.md#download-job-artifacts)
   for the `code_quality` job.
 - The full list of code quality violations generated by a pipeline is shown in the
   Code Quality tab of the Pipeline Details page. **(PREMIUM)**

doc/user/project/pages/introduction.md

@@ -290,7 +290,7 @@ This problem most likely results from a missing `index.html` file in the public
 a 404 is encountered, confirm that the public directory contains an `index.html` file. If the file contains a different name
 such as `test.html`, the Pages site can still be accessed, but the full path would be needed. For example: `https//group-name.pages.example.com/project-name/test.html`.
 
-The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/pipelines/job_artifacts.md#browsing-artifacts) from the latest pipeline.
+The contents of the public directory can be confirmed by [browsing the artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts) from the latest pipeline.
 
 Files listed under the public directory can be accessed through the Pages URL for the project.