Document preserveMetadata flag for Save/Restore Cache (#11569)

* Document preserveMetadata flag for Save/Restore Cache

* Update docs/continuous-integration/shared/preserve-metadata.md

Author: dewan-ahmed

docs/continuous-integration/shared/preserve-metadata.md

@@ -0,0 +1,57 @@
+### Preserve File Metadata
+
+By default, Harness cache steps don’t preserve inode metadata, which means restored files can appear "new" on every build. This can cause cache growth over time, also called **cache snowballing**.
+
+To address this, Harness supports a `preserveMetadata` flag, which can be configured as a stage variable `PLUGIN_PRESERVE_METADATA` set to `true`.
+
+#### How it works
+
+- `preserveMetadata: true`  
+  Cache archives include inode metadata (timestamps, ownership, permissions).  
+  Restored files keep their original metadata, enabling tools like Gradle pruning or `find -atime` to work correctly.
+
+- `preserveMetadata: false` (default)  
+  Metadata is not preserved. Restores are slightly faster, but tools that rely on timestamps treat all files as new.
+
+#### YAML examples
+
+Here’s an example of saving and restoring a Gradle cache with metadata preserved:
+
+```yaml
+steps:
+  - step:
+      type: SaveCache
+      name: save-gradle-cache
+      spec:
+        key: gradle-cache
+        paths:
+          - ~/.gradle
+        preserveMetadata: true
+  - step:
+      type: RestoreCache
+      name: restore-gradle-cache
+      spec:
+        key: gradle-cache
+        preserveMetadata: true
+```
+
+#### Backward compatibility
+
+* The flag is optional and defaults to `false`.
+* Pipelines without this setting continue to work as before.
+* Old cache archives can still be restored even if `preserveMetadata` is enabled.
+
+#### Benefits
+
+* Prevents **cache snowballing** by keeping Gradle cache size stable across builds.
+* Accurate pruning of unused dependencies in Gradle and similar tools.
+* Supports other tools that rely on inode metadata (for example, `find`, cleanup scripts).
+
+#### Troubleshooting
+
+If your Gradle cache grows unexpectedly or pruning doesn’t work:
+
+* Enable `preserveMetadata: true` in both **Save Cache** and **Restore Cache** steps.
+* Make sure the `key` values match across your Save/Restore steps.
+
+

docs/continuous-integration/use-ci/caching-ci-data/save-cache-azure.md

@@ -4,6 +4,8 @@ description: Caching improves build times and enables you to share data across s
 sidebar_position: 41
 ---
 
+import PreserveMetadata from '/docs/continuous-integration/shared/preserve-metadata.md';
+
 You can use the [Cache plugin](https://github.com/drone-plugins/drone-meltwater-cache) in your CI pipelines to save and retrieve cached data from Azure storage.
 
 :::warning
@@ -118,6 +120,8 @@ When using the `cache` plugin to save an Azure cache, the `cache_key` is the Azu
 <+pipeline.variables.AZURE_CONTAINER>/<+pipeline.identifier>/{{ .Commit.Branch }}-{{ checksum "<+pipeline.variables.BUILD_PATH>/build.gradle" }}
 ```
 
+<PreserveMetadata/>
+
 ### Set shared paths for cache locations outside the stage workspace
 
 In a Harness pipeline, all steps in a given stage share the same [workspace](/docs/continuous-integration/use-ci/set-up-build-infrastructure/ci-stage-settings#workspace), which is `/harness`.

docs/continuous-integration/use-ci/caching-ci-data/save-cache-in-gcs.md

@@ -8,6 +8,8 @@ helpdocs_is_private: false
 helpdocs_is_published: true
 ---
 
+import PreserveMetadata from '/docs/continuous-integration/shared/preserve-metadata.md';
+
 Modern continuous integration systems execute pipelines inside ephemeral environments that are provisioned solely for pipeline execution and are not reused from prior pipeline runs. As builds often require downloading and installing many library and software dependencies, caching these dependencies for quick retrieval at runtime can save a significant amount of time.
 
 In addition to loading dependencies faster, you can also use caching to share data across stages in your Harness CI pipelines. You need to use caching to share data across stages because each stage in a Harness CI pipeline has its own build infrastructure.
@@ -198,6 +200,8 @@ Set the timeout limit for the step. Once the timeout limit is reached, the step
 * [Step Skip Condition settings](/docs/platform/pipelines/step-skip-condition-settings.md)
 * [Step Failure Strategy settings](/docs/platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps)
 
+<PreserveMetadata/>
+
 ### Set shared paths for cache locations outside the stage workspace
 
 Steps in the same stage share the same [workspace](/docs/continuous-integration/use-ci/set-up-build-infrastructure/ci-stage-settings#workspace), which is `/harness`. If your steps need to use data in locations outside the stage workspace, you must specify these as [shared paths](/docs/continuous-integration/use-ci/caching-ci-data/share-ci-data-across-steps-and-stages#share-data-between-steps-in-a-stage). This is required if you want to cache directories outside `/harness`. For example:

docs/continuous-integration/use-ci/caching-ci-data/saving-cache.md

@@ -11,6 +11,7 @@ helpdocs_is_published: true
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import PreserveMetadata from '/docs/continuous-integration/shared/preserve-metadata.md';
 
 You can use caching to share data cross stages or run pipelines faster by reusing the expensive fetch operation data from previous builds.
 
@@ -295,6 +296,8 @@ Set the timeout limit for the step. Once the timeout limit is reached, the step
 * [Step Skip Condition settings](/docs/platform/pipelines/step-skip-condition-settings.md)
 * [Step Failure Strategy settings](/docs/platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps)
 
+<PreserveMetadata/>
+
 ### Set shared paths for cache locations outside the stage workspace
 
 Steps in the same stage share the same [workspace](/docs/continuous-integration/use-ci/set-up-build-infrastructure/ci-stage-settings#workspace), which is `/harness`. If your steps need to use data in locations outside the stage workspace, you must specify these as [shared paths](/docs/continuous-integration/use-ci/caching-ci-data/share-ci-data-across-steps-and-stages#share-data-between-steps-in-a-stage). This is required if you want to cache directories outside `/harness`. For example: