feat(docker): pass SOURCE_DATE_EPOCH as build arg for deterministic images

Pass SOURCE_DATE_EPOCH as a Docker build arg to enable deterministic
Docker image timestamps.

Dockerfiles MUST declare ARG SOURCE_DATE_EPOCH for BuildKit to use the
timestamp for image metadata:

  FROM alpine:3.18
  ARG SOURCE_DATE_EPOCH

Without this ARG declaration, images will have non-deterministic
timestamps even though the environment variable is set (from PR #284).

With the ARG, BuildKit uses SOURCE_DATE_EPOCH for:
- Image metadata timestamps (created field)
- History timestamps
- OCI annotations

The ARG is also available in RUN commands for custom build logic:
  RUN go build -ldflags "-X main.BuildTime=$SOURCE_DATE_EPOCH" -o app

Co-authored-by: Ona <no-reply@ona.com>

Author: leodido

README.md

@@ -329,10 +329,39 @@ packages:
 
 **Docker builds:**
 
-For Docker packages, leeway automatically enables BuildKit (`DOCKER_BUILDKIT=1`) and exports `SOURCE_DATE_EPOCH`. For deterministic Docker images, see PR #285 which passes the value as a build arg (requires `ARG SOURCE_DATE_EPOCH` in Dockerfiles).
+For Docker packages, leeway automatically enables BuildKit (`DOCKER_BUILDKIT=1`) and exports `SOURCE_DATE_EPOCH`. Additionally, leeway passes `SOURCE_DATE_EPOCH` as a build arg to enable deterministic image timestamps.
 
 BuildKit is the default builder since Docker Engine v23.0 and is always used in Docker Desktop.
 
+**Dockerfile requirements for deterministic images:**
+
+Dockerfiles MUST declare the build arg for BuildKit to use the timestamp for image metadata:
+
+```dockerfile
+FROM alpine:3.18
+ARG SOURCE_DATE_EPOCH
+COPY app /usr/local/bin/app
+```
+
+With the `ARG SOURCE_DATE_EPOCH` declaration, BuildKit (>= v0.13) automatically uses the timestamp for:
+- Layer creation timestamps
+- Image config `created` timestamp
+- History timestamps
+- OCI annotations
+
+Without the ARG declaration, images will have non-deterministic timestamps even though leeway sets the environment variable.
+
+For multi-stage builds, declare the ARG in each stage:
+
+```dockerfile
+FROM golang:1.21 AS builder
+ARG SOURCE_DATE_EPOCH
+RUN go build -o app
+
+FROM alpine:3.18
+ARG SOURCE_DATE_EPOCH
+COPY --from=builder /app /app
+```
 ## Package Variants
 Leeway supports build-time variance through "package variants". Those variants are defined on the workspace level and can modify the list of sources, environment variables and config of packages.
 For example consider a `WORKSPACE.YAML` with this variants section:

pkg/leeway/build.go

@@ -1992,6 +1992,8 @@ func (p *Package) buildDocker(buildctx *buildContext, wd, result string) (res *p
 		buildcmd = append(buildcmd, "--build-arg", fmt.Sprintf("DEP_%s=%s", arg, val))
 	}
 	buildcmd = append(buildcmd, "--build-arg", fmt.Sprintf("__GIT_COMMIT=%s", p.C.Git().Commit))
+	// Pass SOURCE_DATE_EPOCH for deterministic Docker image timestamps
+	buildcmd = append(buildcmd, "--build-arg", fmt.Sprintf("SOURCE_DATE_EPOCH=%d", mtime))
 	if cfg.Squash {
 		buildcmd = append(buildcmd, "--squash")
 	}