Update artifacts documentation

doc/ci/pipelines/job_artifacts.md

@@ -173,9 +173,8 @@ https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/file/htmlcov/index.
 
 ## When job artifacts are deleted
 
-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.
+See the [`expire_in`](../yaml/README.md#artifactsexpire_in) documentation for information on when
+job artifacts are deleted.
 
 ### Keep artifacts from most recent successful jobs
 

doc/ci/pipelines/pipeline_artifacts.md

@@ -17,4 +17,5 @@ Pipeline artifacts are saved to disk or object storage. They count towards a pro
 
 ## When pipeline artifacts are deleted
 
-The latest artifacts for refs are locked against deletion, and kept regardless of the expiry time.
+See the [`expire_in`](../yaml/README.md#artifactsexpire_in) documentation for information on when
+pipeline artifacts are deleted.

doc/ci/yaml/README.md

@@ -3318,25 +3318,25 @@ Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded us
 
 #### `artifacts:expire_in`
 
-Use `expire_in` to specify how long artifacts are active before they
-expire and are deleted.
-
-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:
-
-- Use the **Keep** button on the job page.
-- Set the value of `expire_in` to `never`. [Available](https://gitlab.com/gitlab-org/gitlab/-/issues/22761)
-  in GitLab 13.3 and later.
-
-After their expiry, artifacts are deleted hourly by default (via a cron job),
-and are not accessible anymore.
-
-The value of `expire_in` is an elapsed time in seconds, unless a unit is
-provided. Examples of valid values:
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0 behind a disabled feature flag, the latest job artifacts are kept regardless of expiry time.
+> - [Made default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8, keeping latest job artifacts can be disabled at the project level.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276583) in GitLab 13.9, keeping latest job artifacts can be disabled instance-wide.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321323) in GitLab 13.12, the latest pipeline artifacts are kept regardless of expiry time.
+
+Use `expire_in` to specify how long [job artifacts](../pipelines/job_artifacts.md) are stored before
+they expire and are deleted. The `expire_in` setting does not affect:
+
+- Artifacts from the latest job, unless this keeping the latest job artifacts is:
+  - [Disabled at the project level](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs).
+  - [Disabled instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
+- [Pipeline artifacts](../pipelines/pipeline_artifacts.md). It's not possible to specify an
+  expiration date for these:
+  - Pipeline artifacts from the latest pipeline are kept forever.
+  - Other pipeline artifacts are erased after one week.
+
+The value of `expire_in` is an elapsed time in seconds, unless a unit is provided. Valid values
+include:
 
 - `'42'`
 - `42 seconds`
@@ -3348,7 +3348,7 @@ provided. Examples of valid values:
 - `3 weeks and 2 days`
 - `never`
 
-To expire artifacts 1 week after being uploaded:
+To expire artifacts one week after being uploaded:
 
 ```yaml
 job:
@@ -3356,12 +3356,19 @@ job:
     expire_in: 1 week
 ```
 
-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)
-in GitLab 13.4.
+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:
+
+- Use the **Keep** button 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`.
 
-In [GitLab 13.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/241026), you can [disable this behavior at the project level in the CI/CD settings](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). In [GitLab 13.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/276583), you can [disable this behavior instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines).
+After their expiry, artifacts are deleted hourly by default (using a cron job), and are not
+accessible anymore.
 
 #### `artifacts:expose_as`