link: add stamped VCS build info

Stamped rules_go binaries cannot report their source revision or dirty
state through runtime/debug or go version -m. This is needed because
users expect the same provenance checks supported by cmd/go-built
module binaries.

Map STABLE_BUILD_SCM_VCS, REVISION, TIME, and STATUS workspace values
to Go's vcs.* settings. Filter those keys in a separate action so
unrelated stable status changes do not relink binaries, normalize times
to UTC, and use the Go 1.20 debug.BuildSetting API directly.

Only stamp executable build info when the target and recorded main
module both come from the main workspace. Preserve that provenance
through embeds and tests so external binaries and wrappers cannot be
misattributed to the caller workspace.

Document the convention and cover stable refreshes, go_binary and
go_test, external provenance, non-executable modes, and stamp inputs.

Author: sluongng

docs/go/core/defines_and_stamping.md

@@ -92,3 +92,36 @@ argument on the command line:
 $ bazel build --stamp --workspace_status_command=./status.sh //:cmd
 ```
 
+### VCS build info
+
+When `go_binary` and `go_test` targets are linked with stamping enabled,
+`rules_go` also maps a small stable workspace status convention into Go build
+info. These settings are visible through `runtime/debug.ReadBuildInfo` and
+`go version -m`. They are only emitted when the linked target and its recorded
+main module both come from the main workspace; stamped binaries built from
+external repositories, targets without main module metadata, and local wrappers
+around external main modules omit `vcs.*` settings. Main-module provenance
+follows the metadata source that supplied `Main.Path`, including embedded
+libraries and `package_metadata` / `applicable_licenses`.
+
+| Workspace status key | Go build info setting | Notes |
+| --- | --- | --- |
+| `STABLE_BUILD_SCM_VCS` | `vcs` | Required and must be non-empty before any `vcs.*` settings are emitted. |
+| `STABLE_BUILD_SCM_REVISION` | `vcs.revision` | Optional when non-empty. |
+| `STABLE_BUILD_SCM_TIME` | `vcs.time` | Optional; must be `RFC3339Nano` and is normalized to UTC. |
+| `STABLE_BUILD_SCM_STATUS` | `vcs.modified` | Optional; `Clean` becomes `false`, `Modified` becomes `true`. |
+
+Invalid or missing optional values are ignored individually.
+
+``` bash
+#!/usr/bin/env bash
+
+echo "STABLE_BUILD_SCM_VCS git"
+echo "STABLE_BUILD_SCM_REVISION $(git rev-parse HEAD)"
+echo "STABLE_BUILD_SCM_TIME $(git show -s --format=%cI HEAD)"
+if test -z "$(git status --porcelain --untracked-files=normal)"; then
+  echo "STABLE_BUILD_SCM_STATUS Clean"
+else
+  echo "STABLE_BUILD_SCM_STATUS Modified"
+fi
+```

go/private/actions/archive.bzl

@@ -197,6 +197,7 @@ def emit_archive(go, source = None, _recompile_suffix = "", recompile_internal_d
         _clinkopts = tuple(source.clinkopts),
         _package_metadata = getattr(source, "_package_metadata", None),
         _main_module_package_metadata = getattr(source, "_main_module_package_metadata", None),
+        _main_module_main_workspace = getattr(source, "_main_module_main_workspace", False),
 
         # Information on dependencies
         _dep_labels = tuple([d.data.label for d in direct]),
@@ -240,4 +241,5 @@ def emit_archive(go, source = None, _recompile_suffix = "", recompile_internal_d
         _headers = headers,
         _package_metadata_files = package_metadata_files,
         _main_module_package_metadata = getattr(data, "_main_module_package_metadata", None),
+        _main_module_main_workspace = getattr(data, "_main_module_main_workspace", False),
     )

go/private/actions/binary.bzl

@@ -37,7 +37,9 @@ def emit_binary(
         executable = None,
         link_exec_group = None,
         buildinfo_path = None,
-        buildinfo_module_metadata = None):
+        buildinfo_module_metadata = None,
+        buildinfo_module_main_workspace = False,
+        main_workspace = True):
     """See go/toolchains.rst#binary for full documentation."""
 
     if name == "" and executable == None:
@@ -46,6 +48,7 @@ def emit_binary(
         buildinfo_path = source.importpath
     if buildinfo_module_metadata == None:
         buildinfo_module_metadata = getattr(source, "_main_module_package_metadata", None)
+        buildinfo_module_main_workspace = getattr(source, "_main_module_main_workspace", False)
 
     archive = go.archive(go, source)
     if not executable:
@@ -66,10 +69,12 @@ def emit_binary(
         test_archives = test_archives,
         buildinfo_path = buildinfo_path,
         buildinfo_module_metadata = buildinfo_module_metadata,
+        buildinfo_module_main_workspace = buildinfo_module_main_workspace,
         executable = executable,
         gc_linkopts = gc_linkopts,
         version_file = version_file,
         info_file = info_file,
+        main_workspace = main_workspace,
         exec_group = link_exec_group,
     )
     cgo_dynamic_deps = [

go/private/actions/link.bzl

@@ -24,6 +24,7 @@ load(
 )
 load(
     "//go/private:mode.bzl",
+    "LINKMODES_EXECUTABLE",
     "LINKMODE_NORMAL",
     "LINKMODE_PLUGIN",
     "extld_from_cc_toolchain",
@@ -37,6 +38,26 @@ load(
 def _format_archive(d):
     return "{}={}={}".format(d.label, d.importmap, d.file.path)
 
+def _should_emit_buildinfo(go):
+    return go.mode.linkmode in LINKMODES_EXECUTABLE
+
+def _emit_vcs_stamp(go, info_file, executable):
+    out = go.actions.declare_file(executable.basename + ".vcsstamp", sibling = executable)
+    args = go.tool_args(go)
+    args.add("vcsstamp")
+    args.add("-in", info_file)
+    args.add("-out", out)
+    go.actions.run(
+        inputs = [info_file],
+        outputs = [out],
+        mnemonic = "GoVCSStamp",
+        executable = go.toolchain._builder,
+        arguments = [args],
+        env = go.env,
+        toolchain = GO_TOOLCHAIN_LABEL,
+    )
+    return out
+
 def emit_link(
         go,
         archive = None,
@@ -47,7 +68,9 @@ def emit_link(
         info_file = None,
         exec_group = None,
         buildinfo_path = None,
-        buildinfo_module_metadata = None):
+        buildinfo_module_metadata = None,
+        buildinfo_module_main_workspace = False,
+        main_workspace = True):
     """See go/toolchains.rst#link for full documentation."""
 
     if archive == None:
@@ -58,6 +81,10 @@ def emit_link(
         buildinfo_path = archive.data.importpath
     if buildinfo_module_metadata == None:
         buildinfo_module_metadata = getattr(archive.data, "_main_module_package_metadata", None)
+        buildinfo_module_main_workspace = getattr(archive.data, "_main_module_main_workspace", False)
+    main_workspace = (main_workspace and
+                      not go.label.repo_name and
+                      not getattr(go.label, "workspace_root", ""))
 
     # Exclude -lstdc++ from link options. We don't want to link against it
     # unless we actually have some C++ code. _cgo_codegen will include it
@@ -177,9 +204,19 @@ def emit_link(
             if count_group_matches(v, "{", "}") != stable_vars_count:
                 stamp_x_defs_volatile = True
 
+    vcs_stamp_file = None
+    if (go.mode.stamp and
+        info_file and
+        main_workspace and
+        buildinfo_module_metadata and
+        buildinfo_module_main_workspace and
+        _should_emit_buildinfo(go)):
+        vcs_stamp_file = _emit_vcs_stamp(go, info_file, executable)
+        builder_args.add("-vcs_stamp", vcs_stamp_file)
+
     # Stamping support
     stamp_inputs = []
-    if stamp_x_defs_stable:
+    if stamp_x_defs_stable and info_file:
         stamp_inputs.append(info_file)
     if stamp_x_defs_volatile:
         stamp_inputs.append(version_file)
@@ -191,6 +228,8 @@ def emit_link(
     builder_args.add("-main_package_path", buildinfo_path)
     if buildinfo_module_metadata:
         builder_args.add("-main_module_metadata", buildinfo_module_metadata)
+    builder_args.add("-main_module_main_workspace=%s" % ("true" if buildinfo_module_main_workspace else "false"))
+    builder_args.add("-main_workspace=%s" % ("true" if main_workspace else "false"))
     builder_args.add("-p", archive.data.importmap)
     tool_args.add_all(gc_linkopts)
     tool_args.add_all(go.toolchain.flags.link)
@@ -204,6 +243,8 @@ def emit_link(
     inputs_direct = stamp_inputs + [go.sdk.package_list]
     if buildinfo_module_metadata:
         inputs_direct.append(buildinfo_module_metadata)
+    if vcs_stamp_file:
+        inputs_direct.append(vcs_stamp_file)
     if go.coverage_enabled and go.coverdata:
         inputs_direct.append(go.coverdata.data.file)
     inputs_transitive = [

go/private/context.bzl

@@ -272,16 +272,26 @@ def _tool_args(go):
     args.use_param_file("-param=%s")
     return args
 
-def package_metadata_file_from_metadata(package_metadata = (), applicable_licenses = ()):
+def _is_main_workspace_label(label):
+    return not label.repo_name and not getattr(label, "workspace_root", "")
+
+def _package_metadata_target_from_metadata(package_metadata = (), applicable_licenses = ()):
     # Bazel may surface repo-level metadata through either spelling depending on
     # the version and rule surface, so probe both.
     for metadata_group in (package_metadata, applicable_licenses):
         for metadata in metadata_group:
             if PackageMetadataInfo in metadata:
-                return metadata[PackageMetadataInfo].metadata
-
+                return metadata
     return None
 
+def package_metadata_file_from_metadata(package_metadata = (), applicable_licenses = ()):
+    metadata = _package_metadata_target_from_metadata(package_metadata, applicable_licenses)
+    return metadata[PackageMetadataInfo].metadata if metadata else None
+
+def package_metadata_main_workspace_from_metadata(package_metadata = (), applicable_licenses = ()):
+    metadata = _package_metadata_target_from_metadata(package_metadata, applicable_licenses)
+    return metadata != None and _is_main_workspace_label(metadata.label)
+
 def _merge_embed(source, embed):
     s = get_source(embed)
     source["srcs"] = s.srcs + source["srcs"]
@@ -297,6 +307,7 @@ def _merge_embed(source, embed):
     main_module_package_metadata = getattr(s, "_main_module_package_metadata", None)
     if not source["_main_module_package_metadata"] and main_module_package_metadata:
         source["_main_module_package_metadata"] = main_module_package_metadata
+        source["_main_module_main_workspace"] = getattr(s, "_main_module_main_workspace", False)
 
     if s.cgo:
         if source["cgo"]:
@@ -408,7 +419,10 @@ def new_go_info(
         getattr(attr, "applicable_licenses", ()),
     )
     package_metadata = main_module_package_metadata if include_package_metadata else None
-
+    main_module_main_workspace = package_metadata_main_workspace_from_metadata(
+        getattr(attr, "package_metadata", ()),
+        getattr(attr, "applicable_licenses", ()),
+    )
     go_info = {
         "name": go.label.name if not name else name,
         "label": go.label,
@@ -435,6 +449,7 @@ def new_go_info(
         "pgoprofile": getattr(attr, "pgoprofile", None),
         "_package_metadata": package_metadata,
         "_main_module_package_metadata": main_module_package_metadata,
+        "_main_module_main_workspace": main_module_main_workspace,
     }
 
     for e in getattr(attr, "embed", []):

go/private/rules/binary.bzl

@@ -155,6 +155,8 @@ def _go_binary_impl(ctx):
         importable = False,
         is_main = is_main,
     )
+    buildinfo_module_metadata = getattr(go_info, "_main_module_package_metadata", None)
+    buildinfo_module_main_workspace = getattr(go_info, "_main_module_main_workspace", False)
     name = ctx.attr.basename
     if not name:
         name = ctx.label.name
@@ -168,9 +170,12 @@ def _go_binary_impl(ctx):
         go,
         name = name,
         source = go_info,
+        buildinfo_module_metadata = buildinfo_module_metadata,
+        buildinfo_module_main_workspace = buildinfo_module_main_workspace,
         gc_linkopts = gc_linkopts(ctx),
         version_file = ctx.version_file,
         info_file = ctx.info_file,
+        main_workspace = not ctx.label.repo_name and not getattr(ctx.label, "workspace_root", ""),
         link_exec_group = "go_link",
         executable = executable,
     )

go/private/rules/test.bzl

@@ -184,17 +184,24 @@ def _go_test_impl(ctx):
         generated_srcs = [main_go],
         coverage_instrumented = False,
     )
-    buildinfo_path = internal_go_info.importpath + ".test" if internal_go_info.importpath else None
+    buildinfo_module_metadata = getattr(internal_go_info, "_main_module_package_metadata", None)
+    buildinfo_module_main_workspace = getattr(internal_go_info, "_main_module_main_workspace", False)
+    buildinfo_path = None
+    if internal_go_info.importpath:
+        buildinfo_path = internal_go_info.importpath + ".test"
+
     test_archive, executable, runfiles = go.binary(
         go,
         name = ctx.label.name,
         source = test_go_info,
         test_archives = [internal_archive.data],
         buildinfo_path = buildinfo_path,
-        buildinfo_module_metadata = getattr(internal_go_info, "_main_module_package_metadata", None),
+        buildinfo_module_metadata = buildinfo_module_metadata,
+        buildinfo_module_main_workspace = buildinfo_module_main_workspace,
         gc_linkopts = test_gc_linkopts,
         version_file = ctx.version_file,
         info_file = ctx.info_file,
+        main_workspace = not ctx.label.repo_name and not getattr(ctx.label, "workspace_root", ""),
         link_exec_group = "go_link",
     )
 
@@ -742,6 +749,8 @@ def _recompile_external_deps(go, external_go_info, internal_archive, library_lab
             cxxopts = list(arc_data._cxxopts),
             clinkopts = list(arc_data._clinkopts),
             _package_metadata = package_metadata,
+            _main_module_package_metadata = getattr(arc_data, "_main_module_package_metadata", None),
+            _main_module_main_workspace = getattr(arc_data, "_main_module_main_workspace", False),
         )
 
         # If this archive needs to be recompiled, use go.archive.
@@ -767,6 +776,8 @@ def _recompile_external_deps(go, external_go_info, internal_archive, library_lab
                     direct = [package_metadata] if package_metadata else [],
                     transitive = [getattr(a, "_package_metadata_files", depset()) for a in deps],
                 ),
+                _main_module_package_metadata = getattr(arc_data, "_main_module_package_metadata", None),
+                _main_module_main_workspace = getattr(arc_data, "_main_module_main_workspace", False),
             )
         label_to_archive[label] = archive
 

go/toolchains.rst

@@ -769,6 +769,7 @@ It returns a tuple containing GoArchive_, the output executable file, and
 a ``runfiles`` object.
 
 .. |module metadata| replace:: :param:`buildinfo_module_metadata`
+.. |module provenance| replace:: :param:`buildinfo_module_main_workspace`
 
 +--------------------------------+-----------------------------+-----------------------------------+
 | **Name**                       | **Type**                    | **Default value**                 |
@@ -815,6 +816,16 @@ a ``runfiles`` object.
 | Package metadata JSON file used to populate ``BuildInfo.Main``. Defaults to the metadata         |
 | propagated by :param:`source`.                                                                   |
 +--------------------------------+-----------------------------+-----------------------------------+
+| |module provenance|            | :type:`bool`                | :value:`False`                    |
++--------------------------------+-----------------------------+-----------------------------------+
+| Whether :param:`buildinfo_module_metadata` comes from the main workspace. Inferred when the      |
+| metadata defaults from :param:`source`; controls whether stamped ``vcs.*`` settings are emitted. |
++--------------------------------+-----------------------------+-----------------------------------+
+| :param:`main_workspace`        | :type:`bool`                | :value:`True`                     |
++--------------------------------+-----------------------------+-----------------------------------+
+| Whether the binary target comes from the main workspace. Set this to ``False`` for custom rules  |
+| that link targets in external repositories so caller workspace VCS data is not attributed to it. |
++--------------------------------+-----------------------------+-----------------------------------+
 
 
 link
@@ -867,6 +878,17 @@ It does not return anything.
 | Package metadata JSON file used to populate ``BuildInfo.Main``. Defaults to metadata propagated  |
 | by :param:`archive`.                                                                             |
 +--------------------------------+-----------------------------+-----------------------------------+
+| |module provenance|            | :type:`bool`                | :value:`False`                    |
++--------------------------------+-----------------------------+-----------------------------------+
+| Whether :param:`buildinfo_module_metadata` comes from the main workspace. Inferred when the      |
+| metadata defaults from :param:`archive`; controls whether stamped ``vcs.*`` settings are         |
+| emitted.                                                                                          |
++--------------------------------+-----------------------------+-----------------------------------+
+| :param:`main_workspace`        | :type:`bool`                | :value:`True`                     |
++--------------------------------+-----------------------------+-----------------------------------+
+| Whether the linked target comes from the main workspace. Set this to ``False`` for external      |
+| repository targets to avoid attributing caller workspace VCS data to them.                       |
++--------------------------------+-----------------------------+-----------------------------------+
 
 
 args

go/tools/builders/BUILD.bazel

@@ -104,6 +104,15 @@ go_test(
     ],
 )
 
+go_test(
+    name = "stamp_test",
+    size = "small",
+    srcs = [
+        "stamp.go",
+        "stamp_test.go",
+    ],
+)
+
 go_test(
     name = "nogo_version_test",
     size = "small",
@@ -145,8 +154,10 @@ filegroup(
         "nogo_validation.go",
         "read.go",
         "replicate.go",
+        "stamp.go",
         "stdlib.go",
         "stdliblist.go",
+        "vcsstamp.go",
     ] + select({
         "@bazel_tools//src/conditions:windows": ["path_windows.go"],
         "//conditions:default": ["path.go"],

go/tools/builders/builder.go

@@ -59,6 +59,8 @@ func main() {
 		action = genTestMain
 	case "link":
 		action = link
+	case "vcsstamp":
+		action = vcsStamp
 	case "gennogomain":
 		action = genNogoMain
 	case "stdlib":