Skip to content

build: WORKDIR+SOURCE_DATE_EPOCH cache invalidation #23795

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dvdksn merged 1 commit into from
Dec 2, 2025
Merged

build: WORKDIR+SOURCE_DATE_EPOCH cache invalidation #23795

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions content/manuals/build/cache/invalidation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down