oci: add SOURCE_DATE_EPOCH support for reproducible builds

Add support for SOURCE_DATE_EPOCH environment variable to enable
reproducible builds by eliminating timestamp-based non-determinism.

The implementation follows the tar --clamp-mtime behavior, only
modifying timestamps newer than SOURCE_DATE_EPOCH while preserving
historical timestamps. This affects new, repack, insert, and config
commands.

Signed-off-by: Danish Prakash <contact@danishpraka.sh>

Author: danishprakash

cmd/umoci/config.go

@@ -293,9 +293,17 @@ func config(ctx *cli.Context) (Err error) {
 		}
 	}
 
+	sourceDateEpoch, err := parseSourceDateEpoch()
+	if err != nil {
+		return err
+	}
+
 	var history *ispec.History
 	if !ctx.Bool("no-history") {
 		created := time.Now()
+		if !sourceDateEpoch.IsZero() {
+			created = sourceDateEpoch
+		}
 		history = &ispec.History{
 			Author:     g.Author(),
 			Comment:    "",

cmd/umoci/insert.go

@@ -165,17 +165,26 @@ func insert(ctx *cli.Context) (Err error) {
 		return err
 	}
 
+	sourceDateEpoch, err := parseSourceDateEpoch()
+	if err != nil {
+		return err
+	}
+
 	packOptions := layer.RepackOptions{
 		OnDiskFormat: layer.DirRootfs{
 			MapOptions: meta.MapOptions,
 		},
+		SourceDateEpoch: sourceDateEpoch,
 	}
 	reader := layer.GenerateInsertLayer(sourcePath, targetPath, ctx.IsSet("opaque"), &packOptions)
 	defer funchelpers.VerifyClose(&Err, reader)
 
 	var history *ispec.History
 	if !ctx.Bool("no-history") {
 		created := time.Now()
+		if !sourceDateEpoch.IsZero() {
+			created = sourceDateEpoch
+		}
 		history = &ispec.History{
 			Comment:    "",
 			Created:    &created,
@@ -189,6 +198,8 @@ func insert(ctx *cli.Context) (Err error) {
 		if ctx.IsSet("history.comment") {
 			history.Comment = ctx.String("history.comment")
 		}
+
+		// cli flag takes precedence over SOURCE_DATE_EPOCH, if set
 		if ctx.IsSet("history.created") {
 			created, err := time.Parse(igen.ISO8601, ctx.String("history.created"))
 			if err != nil {

cmd/umoci/new.go

@@ -60,6 +60,11 @@ func newImage(ctx *cli.Context) (Err error) {
 	imagePath := mustFetchMeta[string](ctx, "--image-path")
 	tagName := mustFetchMeta[string](ctx, "--image-tag")
 
+	sourceDateEpoch, err := parseSourceDateEpoch()
+	if err != nil {
+		return err
+	}
+
 	// Get a reference to the CAS.
 	engine, err := dir.Open(imagePath)
 	if err != nil {
@@ -68,5 +73,5 @@ func newImage(ctx *cli.Context) (Err error) {
 	engineExt := casext.NewEngine(engine)
 	defer funchelpers.VerifyClose(&Err, engine)
 
-	return umoci.NewImage(engineExt, tagName)
+	return umoci.NewImage(engineExt, tagName, sourceDateEpoch)
 }

cmd/umoci/raw-add-layer.go

@@ -134,9 +134,17 @@ func rawAddLayer(ctx *cli.Context) (Err error) {
 		return fmt.Errorf("get image metadata: %w", err)
 	}
 
+	sourceDateEpoch, err := parseSourceDateEpoch()
+	if err != nil {
+		return err
+	}
+
 	var history *ispec.History
 	if !ctx.Bool("no-history") {
 		created := time.Now()
+		if !sourceDateEpoch.IsZero() {
+			created = sourceDateEpoch
+		}
 		history = &ispec.History{
 			Author:     imageMeta.Author,
 			Comment:    "",

cmd/umoci/repack.go

@@ -152,9 +152,17 @@ func repack(ctx *cli.Context) (Err error) {
 		return fmt.Errorf("get image metadata: %w", err)
 	}
 
+	sourceDateEpoch, err := parseSourceDateEpoch()
+	if err != nil {
+		return err
+	}
+
 	var history *ispec.History
 	if !ctx.Bool("no-history") {
 		created := time.Now()
+		if !sourceDateEpoch.IsZero() {
+			created = sourceDateEpoch
+		}
 		history = &ispec.History{
 			Author:     imageMeta.Author,
 			Comment:    "",
@@ -185,5 +193,5 @@ func repack(ctx *cli.Context) (Err error) {
 		mtreefilter.MaskFilter(maskedPaths),
 	}
 
-	return umoci.Repack(engineExt, tagName, bundlePath, meta, history, filters, ctx.Bool("refresh-bundle"), mutator, compressAlgo)
+	return umoci.Repack(engineExt, tagName, bundlePath, meta, history, filters, ctx.Bool("refresh-bundle"), mutator, compressAlgo, sourceDateEpoch)
 }

cmd/umoci/utils.go

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+/*
+ * umoci: Umoci Modifies Open Containers' Images
+ * Copyright (C) 2016-2025 SUSE LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Package main contains utility functions for umoci commands.
+package main
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+	"time"
+)
+
+// parseSourceDateEpoch parses the SOURCE_DATE_EPOCH environment variable
+// and returns the corresponding time.Time, or zero time if not set.
+func parseSourceDateEpoch() (time.Time, error) {
+	sourceDateEpochStr := os.Getenv("SOURCE_DATE_EPOCH")
+	if sourceDateEpochStr == "" {
+		return time.Time{}, nil
+	}
+
+	timestamp, err := strconv.ParseInt(sourceDateEpochStr, 10, 64)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("parsing SOURCE_DATE_EPOCH %q: %w", sourceDateEpochStr, err)
+	}
+
+	return time.Unix(timestamp, 0).UTC(), nil
+}

cmd/umoci/utils_test.go

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+/*
+ * umoci: Umoci Modifies Open Containers' Images
+ * Copyright (C) 2016-2025 SUSE LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package main
+
+import (
+	"os"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseSourceDateEpoch(t *testing.T) {
+	t.Run("EmptyEnvironmentVariable", func(t *testing.T) {
+		require.NoError(t, os.Unsetenv("SOURCE_DATE_EPOCH"))
+
+		result, err := parseSourceDateEpoch()
+
+		require.NoError(t, err)
+		assert.True(t, result.IsZero())
+	})
+
+	t.Run("ValidTimestamp", func(t *testing.T) {
+		t.Setenv("SOURCE_DATE_EPOCH", "1234567890")
+
+		result, err := parseSourceDateEpoch()
+
+		require.NoError(t, err)
+		assert.False(t, result.IsZero())
+		assert.Equal(t, int64(1234567890), result.Unix())
+		assert.Equal(t, time.UTC, result.Location())
+	})
+
+	t.Run("InvalidFormat", func(t *testing.T) {
+		t.Setenv("SOURCE_DATE_EPOCH", "not-a-number")
+
+		result, err := parseSourceDateEpoch()
+
+		require.Error(t, err)
+		assert.True(t, result.IsZero())
+		assert.Contains(t, err.Error(), "parsing SOURCE_DATE_EPOCH")
+	})
+}

new.go

@@ -33,7 +33,7 @@ import (
 )
 
 // NewImage creates a new empty image (tag) in the existing layout.
-func NewImage(engineExt casext.Engine, tagName string) error {
+func NewImage(engineExt casext.Engine, tagName string, sourceDateEpoch time.Time) error {
 	// Create a new manifest.
 	log.WithFields(log.Fields{
 		"tag": tagName,
@@ -42,6 +42,9 @@ func NewImage(engineExt casext.Engine, tagName string) error {
 	// Create a new image config.
 	g := igen.New()
 	createTime := time.Now()
+	if !sourceDateEpoch.IsZero() {
+		createTime = sourceDateEpoch
+	}
 
 	// Set all of the defaults we need.
 	g.SetCreated(createTime)

oci/layer/tar_generate.go

@@ -26,6 +26,7 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"time"
 
 	"github.com/apex/log"
 	"golang.org/x/sys/unix"
@@ -52,6 +53,10 @@ type tarGenerator struct {
 	// fsEval is an fseval.FsEval used for extraction.
 	fsEval fseval.FsEval
 
+	// sourceDateEpoch, if set, clamps file timestamps in the generated tar
+	// to not be newer than this time (follows tar --clamp-mtime behavior).
+	sourceDateEpoch time.Time
+
 	// XXX: Should we add a safety check to make sure we don't generate two of
 	//      the same path in a tar archive? This is not permitted by the spec.
 }
@@ -67,10 +72,11 @@ func newTarGenerator(w io.Writer, opt *RepackOptions) *tarGenerator {
 	}
 
 	return &tarGenerator{
-		tw:        tar.NewWriter(w),
-		onDiskFmt: opt.OnDiskFormat,
-		inodes:    map[uint64]string{},
-		fsEval:    fsEval,
+		tw:              tar.NewWriter(w),
+		onDiskFmt:       opt.OnDiskFormat,
+		inodes:          map[uint64]string{},
+		fsEval:          fsEval,
+		sourceDateEpoch: opt.SourceDateEpoch,
 	}
 }
 
@@ -126,6 +132,22 @@ func (tg *tarGenerator) AddFile(name, path string) (Err error) {
 	if err != nil {
 		return fmt.Errorf("convert fi to hdr: %w", err)
 	}
+
+	// Apply SOURCE_DATE_EPOCH timestamp clamping if set.
+	// Only clamp timestamps that are newer than SOURCE_DATE_EPOCH
+	// effectively following tar --clamp-mtime behavior.
+	if !tg.sourceDateEpoch.IsZero() {
+		sourceDateEpoch := tg.sourceDateEpoch
+		if !hdr.ModTime.IsZero() && hdr.ModTime.After(sourceDateEpoch) {
+			hdr.ModTime = sourceDateEpoch
+		}
+		if !hdr.AccessTime.IsZero() && hdr.AccessTime.After(sourceDateEpoch) {
+			hdr.AccessTime = sourceDateEpoch
+		}
+		if !hdr.ChangeTime.IsZero() && hdr.ChangeTime.After(sourceDateEpoch) {
+			hdr.ChangeTime = sourceDateEpoch
+		}
+	}
 	hdr.Xattrs = map[string]string{} //nolint:staticcheck // SA1019: Xattrs is deprecated but PAXRecords is more annoying
 	// Usually incorrect for containers and was added in Go 1.10 causing
 	// changes to our output on a compiler bump...