Merge pull request #9506 from circleci/EXEC-5563-add-job-level-cache-retention

[EXEC-5563] Add job retention documentation with config.yml example

Author: ahmedwab

docs/guides/modules/optimize/pages/persist-data.adoc

@@ -139,6 +139,26 @@ When you have determined your preferred storage retention for each object type,
 
 The *Reset to Default Values* button will reset the object types to their default storage retention periods: 30 days for artifacts, and 15 days for caches and workspaces.
 
+You can also configure job retention periods to control how long job data is kept. Job retention specifically controls cache retention at the job level. This setting can be configured from 1 day to 15 days using string values (for example, "1d", "7d", "15d") in your CircleCI configuration YAML file. Job retention reduces the organization-level retention from the default by automatically removing cache data after the specified period.
+
+The following example shows how to configure job retention in your configuration file:
+
+[source,yaml]
+----
+version: 2.1
+
+jobs:
+  test:
+    docker:
+      - image: cimg/node:18.0
+    retention:
+      caches: 7d
+    steps:
+      - checkout
+      - run: npm install
+      - run: npm test
+----
+
 Anyone in the organization can view the custom usage controls, but you must be an admin to make changes to the storage periods.
 
 image::guides:ROOT:storage-usage-controls.png[storage-usage-controls]

docs/reference/modules/ROOT/pages/configuration-reference.adoc

@@ -380,6 +380,11 @@ Each job consists of the job's name as a key and a map as a value. A name should
 | N
 | String
 | Amount of CPU and RAM allocated to each container in a job.
+
+| `retention`
+| N
+| Map
+| Configure job retention periods for cache data (1-15 days, for example, "1d", "7d", "15d"). Reduces organization-level retention by automatically removing cache data after the specified period.
 |===
 
 ^(1)^ One executor type should be specified per job. If more than one is set you will receive an error.
@@ -484,6 +489,33 @@ jobs:
 
 '''
 
+[#retention]
+==== `retention`
+
+Configure job retention periods to control how long job data is kept. Job retention specifically controls cache retention at the job level. This setting can be configured from 1 day to 15 days using string values (for example, "1d", "7d", "15d"). Job retention reduces the organization-level retention from the default by automatically removing cache data after the specified period.
+
+For more information on cache retention, see the xref:guides:optimize:persist-data.adoc#custom-storage-usage[Persisting data overview] page.
+
+*Example:*
+
+[source,yaml]
+----
+version: 2.1
+
+jobs:
+  test:
+    docker:
+      - image: cimg/node:18.0
+    retention:
+      caches: 7d
+    steps:
+      - checkout
+      - run: npm install
+      - run: npm test
+----
+
+'''
+
 [#parallelism]
 ==== `parallelism`