From 4865382560c3ef9a7759bf113bd3be16cd090dd3 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 2 Dec 2025 12:08:44 +0100
Subject: [PATCH] build: WORKDIR+SOURCE_DATE_EPOCH cache invalidation

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/manuals/build/cache/invalidation.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/content/manuals/build/cache/invalidation.md b/content/manuals/build/cache/invalidation.md
index 535f3df28162..f01c6b1d0c4e 100644
--- a/content/manuals/build/cache/invalidation.md
+++ b/content/manuals/build/cache/invalidation.md
@@ -44,6 +44,23 @@ If your build contains several layers and you want to ensure the build cache is
 reusable, order the instructions from less frequently changed to more
 frequently changed where possible.
 
+## WORKDIR and SOURCE_DATE_EPOCH
+
+The `WORKDIR` instruction respects the `SOURCE_DATE_EPOCH` build argument when
+determining cache validity. Changing `SOURCE_DATE_EPOCH` between builds
+invalidates the cache for `WORKDIR` and all subsequent instructions.
+
+`SOURCE_DATE_EPOCH` sets timestamps for files created during the build. If you
+set this to a dynamic value like a Git commit timestamp, the cache breaks with
+each commit. This is expected behavior when tracking build provenance.
+
+For reproducible builds without frequent cache invalidation, use a fixed
+timestamp:
+
+```console
+$ docker build --build-arg SOURCE_DATE_EPOCH=0 .
+```
+
 ## RUN instructions
 
 The cache for `RUN` instructions isn't invalidated automatically between builds.