buildx bake: provide access to SOURCE_DATE_EPOCH as an RFC3339 timestamp string

[sdavids]

Contributing guidelines

• I've read the contributing guidelines and wholeheartedly agree

I've found a bug and checked that ...

• ... the documentation does not mention anything about my problem
• ... there are no open or closed issues that are related to my problem

Description

I want to be able to set the org.opencontainers.image.created label via SOURCE_DATE_EPOCH.

Expected behaviour

There should be a way to access SOURCE_DATE_EPOCH as a RFC3339 timestamp string.

https://developer.hashicorp.com/terraform/language/functions/timestamp

timestamp returns a UTC timestamp string in RFC 3339 format.
[…]
The result of this function will change every second […] For more stable time handling, see the Time Provider.

Maybe timestamp() could return the value of SOURCE_DATE_EPOCH if set?

target "test" {
  labels = {
    "org.opencontainers.image.created" = timestamp()
  }
}

Alternatively, there would be a function similar to provider::time::unix_timestamp_parse.

Actual behaviour

• SOURCE_DATE_EPOCH cannot be accessed as a RFC3339 timestamp string

• provider::time::unix_timestamp_parse cannot be used

Buildx version

github.com/docker/buildx v0.23.0-desktop.1 503f948aadbddb6de3ec5581f766e1d27f6975a1

Docker info

Client:
 Version:    28.1.1
 Context:    desktop-linux
 Debug Mode: false
 Plugins:
  ai: Docker AI Agent - Ask Gordon (Docker Inc.)
    Version:  v1.1.7
    Path:     /Users/redacted/.docker/cli-plugins/docker-ai
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.23.0-desktop.1
    Path:     /Users/redacted/.docker/cli-plugins/docker-buildx
  cloud: Docker Cloud (Docker Inc.)
    Version:  v0.3.0
    Path:     /Users/redacted/.docker/cli-plugins/docker-cloud
  compose: Docker Compose (Docker Inc.)
    Version:  v2.35.1-desktop.1
    Path:     /Users/redacted/.docker/cli-plugins/docker-compose
  debug: Get a shell into any image or container (Docker Inc.)
    Version:  0.0.38
    Path:     /Users/redacted/.docker/cli-plugins/docker-debug
  desktop: Docker Desktop commands (Docker Inc.)
    Version:  v0.1.8
    Path:     /Users/redacted/.docker/cli-plugins/docker-desktop
  dev: Docker Dev Environments (Docker Inc.)
    Version:  v0.1.2
    Path:     /Users/redacted/.docker/cli-plugins/docker-dev
  extension: Manages Docker extensions (Docker Inc.)
    Version:  v0.2.27
    Path:     /Users/redacted/.docker/cli-plugins/docker-extension
  init: Creates Docker-related starter files for your project (Docker Inc.)
    Version:  v1.4.0
    Path:     /Users/redacted/.docker/cli-plugins/docker-init
  mcp: Docker MCP Plugin (Docker Inc.)
    Version:  dev
    Path:     /Users/dev/.docker/cli-plugins/docker-mcp
  sbom: View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc.)
    Version:  0.6.0
    Path:     /Users/redacted/.docker/cli-plugins/docker-sbom
  scout: Docker Scout (Docker Inc.)
    Version:  v1.17.1
    Path:     /Users/redacted/.docker/cli-plugins/docker-scout

Server:
 Containers: 1
  Running: 0
  Paused: 0
  Stopped: 1
 Images: 13
 Server Version: 28.1.1
 Storage Driver: overlayfs
  driver-type: io.containerd.snapshotter.v1
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
 CDI spec directories:
  /etc/cdi
  /var/run/cdi
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 05044ec0a9a75232cad458027ca83437aae3f4da
 runc version: v1.2.5-0-g59923ef
 init version: de40ad0
 Security Options:
  seccomp
   Profile: unconfined
  cgroupns
 Kernel Version: 6.10.14-linuxkit
 Operating System: Docker Desktop
 OSType: linux
 Architecture: x86_64
 CPUs: 8
 Total Memory: 7.656GiB
 Name: docker-desktop
 ID: ca550c22-08a5-4e2b-ace8-d6196ec5b543
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 HTTP Proxy: http.docker.internal:3128
 HTTPS Proxy: http.docker.internal:3128
 No Proxy: hubproxy.docker.internal
 Labels:
  com.docker.desktop.address=unix:///Users/dev/Library/Containers/com.docker.docker/Data/docker-cli.sock
 Experimental: false
 Insecure Registries:
  hubproxy.docker.internal:5555
  ::1/128
  127.0.0.0/8
 Live Restore Enabled: false

Builders list

NAME/NODE           DRIVER/ENDPOINT     STATUS    BUILDKIT   PLATFORMS
default             docker                                   
 \_ default          \_ default         running   v0.21.0    linux/amd64 (+2), linux/arm64, linux/arm (+2), linux/ppc64le, (2 more)
desktop-linux*      docker                                   
 \_ desktop-linux    \_ desktop-linux   running   v0.21.0    linux/amd64 (+2), linux/arm64, linux/arm (+2), linux/ppc64le, (2 more)

Configuration

FROM scratch

variable "BUILD_TIME" {
  type     = string
  default  = timestamp()
}
variable "SOURCE_DATE_EPOCH" {
  type     = number
}
group "default" {
  targets = ["test"]
}
target "test" {
  tags = ["baked"]
  labels = {
    "org.opencontainers.image.created" = "${BUILD_TIME}"
    "epoch" = "${SOURCE_DATE_EPOCH}"
  }
}

$ SOURCE_DATE_EPOCH=0 docker buildx build -t test .
$ SOURCE_DATE_EPOCH=0 docker buildx bake

$ docker inspect test
[
    {
        "Id": "sha256:3a58ad119f0dae830e39299dd9d94100e3a764665fba8810f9a873d3ac716aec",
        "RepoTags": [
            "test:latest"
        ],
        "RepoDigests": [
            "test@sha256:3a58ad119f0dae830e39299dd9d94100e3a764665fba8810f9a873d3ac716aec"
        ],
        "Parent": "",
        "Comment": "",
        "DockerVersion": "",
        "Author": "",
        "Config": {
            "Hostname": "",
            "Domainname": "",
            "User": "",
            "AttachStdin": false,
            "AttachStdout": false,
            "AttachStderr": false,
            "Tty": false,
            "OpenStdin": false,
            "StdinOnce": false,
            "Env": [
                "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
            ],
            "Cmd": null,
            "Image": "",
            "Volumes": null,
            "WorkingDir": "/",
            "Entrypoint": null,
            "OnBuild": null,
            "Labels": null
        },
        "Architecture": "amd64",
        "Os": "linux",
        "Size": 518,
        "GraphDriver": {
            "Data": null,
            "Name": "overlayfs"
        },
        "RootFS": {
            "Type": "layers"
        },
        "Metadata": {
            "LastTagTime": "1970-01-01T00:00:00Z"
        },
        "Descriptor": {
            "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
            "digest": "sha256:3a58ad119f0dae830e39299dd9d94100e3a764665fba8810f9a873d3ac716aec",
            "size": 304,
            "annotations": {
                "config.digest": "sha256:471a1b8817eefb6569017c1a76f288e0d4e5c8476eb199485c469d0b033168bf"
            }
        }
    }
]
$ docker inspect baked
[
    {
        "Id": "sha256:2dde41d15026c98ba86bd04748102d70ddefb4a92208dde271ba9f0228c2e920",
        "RepoTags": [
            "baked:latest"
        ],
        "RepoDigests": [
            "baked@sha256:2dde41d15026c98ba86bd04748102d70ddefb4a92208dde271ba9f0228c2e920"
        ],
        "Parent": "",
        "Comment": "",
        "DockerVersion": "",
        "Author": "",
        "Config": {
            "Hostname": "",
            "Domainname": "",
            "User": "",
            "AttachStdin": false,
            "AttachStdout": false,
            "AttachStderr": false,
            "Tty": false,
            "OpenStdin": false,
            "StdinOnce": false,
            "Env": [
                "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
            ],
            "Cmd": null,
            "Image": "",
            "Volumes": null,
            "WorkingDir": "/",
            "Entrypoint": null,
            "OnBuild": null,
            "Labels": {
                "epoch": "0",
                "org.opencontainers.image.created": "2025-05-20T14:56:18Z"
            }
        },
        "Architecture": "amd64",
        "Os": "linux",
        "Size": 599,
        "GraphDriver": {
            "Data": null,
            "Name": "overlayfs"
        },
        "RootFS": {
            "Type": "layers"
        },
        "Metadata": {
            "LastTagTime": "1970-01-01T00:00:00Z"
        },
        "Descriptor": {
            "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
            "digest": "sha256:2dde41d15026c98ba86bd04748102d70ddefb4a92208dde271ba9f0228c2e920",
            "size": 304,
            "annotations": {
                "config.digest": "sha256:8f94f276f13134f47a434228684fca44e0e0e4fb08f79b5dc8c76ea37225bc66"
            }
        }
    }
]

Build logs

Additional info

• https://reproducible-builds.org/docs/source-date-epoch/
• https://registry.terraform.io/providers/hashicorp/time/latest/docs/functions/unix_timestamp_parse
• https://developer.hashicorp.com/terraform/language/functions/timestamp
• https://github.com/opencontainers/image-spec/blob/main/annotations.md#pre-defined-annotation-keys

[sdavids]

One could pass BUILD_TIME from the outside but it would not be DRY and unfortunately BSD/Linux date have different flags, e.g.:

SOURCE_DATE_EPOCH="$(git log --max-count=1 --pretty=format:%ct)"

if [ "$(uname)" = 'Darwin' ]; then
  BUILD_TIME="$(date -r "${SOURCE_DATE_EPOCH}" -Iseconds -u | sed -e 's/+00:00$/Z/')"
else
  BUILD_TIME="$(date -d "@${SOURCE_DATE_EPOCH}" -Iseconds -u | sed -e 's/+00:00$/Z/')"
fi

[crazy-max]

I was thinking you could use formatdate but format is limited and X is not supported:

variable "BUILD_TIME" {
  type     = string
  default  = timestamp()
}
variable "SOURCE_DATE_EPOCH" {
  type     = number
  default  = formatdate("X", timestamp())
}
group "default" {
  targets = ["test"]
}
target "test" {
  tags = ["baked"]
  labels = {
    "org.opencontainers.image.created" = "${BUILD_TIME}"
    "epoch" = "${SOURCE_DATE_EPOCH}"
  }
}

$ docker buildx bake --print
#1 [internal] load local bake definitions
#1 reading docker-bake.hcl 355B / 355B done
#1 DONE 0.0s
docker-bake.hcl:7
--------------------
   5 |     variable "SOURCE_DATE_EPOCH" {
   6 |       type     = number
   7 | >>>   default  = formatdate("X", timestamp())
   8 |     }
   9 |     group "default" {
--------------------
ERROR: docker-bake.hcl:7,26-27: Invalid function argument; Invalid value for "format" parameter: invalid date format verb "X".

I think we could either support more formats or maybe have something similar to time_static

[sdavids]

SOURCE_DATE_EPOCH - A UNIX timestamp, defined as the number of seconds, excluding leap seconds, since 01 Jan 1970 00:00:00 UTC

formatdate requires a timestamp in RFC 3339 "Date and Time format" syntax.

—--

time_static.build_time set to SOURCE_DATE_EPOCH or the current timestamp if not set is another option.

time_static.build_time.rfc3339

—--

A conversion function (unix to rfc3339 timestamp) would have more use cases though.

[tonistiigi]

If we added support that the timestamp passed to formatdate (2nd param) can be unix timestamp, would that fix the issue? We could do it by just checking if it only contains numbers.

We could also consider something special for the reverse behavior of formatting timestamp RFC3339 timestamp into unix, but I think that would require upstream go-cty change (or bunch of copy-paste).

[sdavids]

If we added support that the timestamp passed to formatdate (2nd param) can be unix timestamp, would that fix the issue?

I am not sure if it is a good idea.

It mainly depends on how you see Docker's use of HCL:

a) HCL syntax only
b) syntax and built-in functions
c) syntax, built-in functions, and XYX

---

If built-in functions are supported then I think they should be kept closely aligned with the Terraform functions to maximize knowledge transfer.

Let's not have the GNU/BSD sed situation again.