Document v0.0.3 hostname home-host contract

README.md

@@ -114,10 +114,22 @@ A pin key is `OWNER/REPO@REF`. The same key appears in both `workflows` (as
 flat transitive lists) and `dependencies` (as deduplicated graph entries with
 `uses:` links to direct dependencies).
 
-The `hostname` field is optional in v0.0.3. Dotcom-only producers may omit it.
-Hostname-aware producers running in Proxima record the canonical hostname for
-every direct and transitive dependency, including `github.com` dependencies in
-mixed graphs. When present, `hostname` must be the bare lowercase `github.com`
+The `hostname` field is optional in v0.0.3. An omitted `hostname` binds the
+pin to the home host: the tenant (`<tenant>.ghe.com`) on a GHE.com
+data-residency instance, or `github.com` on github.com.
+
+- Producers must omit `hostname` for pins bound to the home host. The only
+  value producers write explicitly is `github.com`, for pins bound to
+  github.com while running on a GHE.com data-residency instance. Producers
+  never write a `*.ghe.com` hostname.
+- On github.com, `hostname` must be omitted or `github.com`. Any other value
+  is rejected.
+- On GHE.com data-residency instances, only v0.0.3 lockfiles are accepted.
+  v0.0.1 and v0.0.2 lockfiles used omission to mean github.com, so producers
+  migrate them to v0.0.3 with an explicit `github.com` hostname on every
+  dependency.
+
+Syntactically, a present `hostname` must be the bare lowercase `github.com`
 hostname or a lowercase GHE tenant hostname such as `octocorp.ghe.com`.
 
 The parser also reads the dotcom-only v0.0.1 and v0.0.2 lockfiles, defaulting

go/pkg/lockfile/lockfile.go

@@ -86,7 +86,6 @@ const CLIName = "gh actions-lock"
 //	    - actions/checkout@v6
 //	dependencies:
 //	  actions/checkout@v4.3.1:
-//	    hostname: github.com
 //	    ref: v4.3.1
 //	    commit: sha1-34e114876b0b11c390a56381ad16ebd13914f8d5
 //	    owner_id: 44036562
@@ -215,23 +214,24 @@ func (f File) LookupWorkflow(workflowKey string) ([]string, bool) {
 }
 
 // Action carries the per-action metadata recorded under a pin key.
-//
-// Hostname is the optional bare canonical hostname of the GitHub instance that
-// owns the dependency: github.com or a lowercase GHE tenant hostname such as
-// octocorp.ghe.com. It is empty when omitted. Ref is the git ref the commit was
-// resolved from (required). Commit is the digest in algo-prefixed form (e.g.
-// "sha1-abc123...", "sha256-def456...") (required). OwnerID and RepoID are the
-// host-specific numeric IDs for the owner and repository, used to detect a
-// repository transfer (the name changes but the ID does not). Uses lists the
-// action's direct nested dependencies as canonical pin keys — empty for leaf
-// actions, populated for composite actions.
 type Action struct {
-	Hostname string   `yaml:"hostname,omitempty"`
-	Ref      string   `yaml:"ref,omitempty"`
-	Commit   string   `yaml:"commit,omitempty"`
-	OwnerID  int64    `yaml:"owner_id"`
-	RepoID   int64    `yaml:"repo_id"`
-	Uses     []string `yaml:"uses,omitempty"`
+	// Hostname is the GitHub instance that owns the dependency. Empty means
+	// the home host: the tenant on a GHE.com data-residency instance, or
+	// github.com on github.com. Producers set it only to github.com, for
+	// github.com-bound pins on a GHE.com data-residency instance.
+	Hostname string `yaml:"hostname,omitempty"`
+	// Ref is the git ref the commit was resolved from (required).
+	Ref string `yaml:"ref,omitempty"`
+	// Commit is the digest in algo-prefixed form, e.g. "sha1-abc123..."
+	// (required).
+	Commit string `yaml:"commit,omitempty"`
+	// OwnerID and RepoID are the host-specific numeric IDs for the owner and
+	// repository, used to detect a transfer (the name changes, the ID does not).
+	OwnerID int64 `yaml:"owner_id"`
+	RepoID  int64 `yaml:"repo_id"`
+	// Uses lists the action's direct nested dependencies as canonical pin
+	// keys: empty for leaf actions, populated for composite actions.
+	Uses []string `yaml:"uses,omitempty"`
 }
 
 // MaxParseSize is the maximum number of bytes Parse accepts. Larger inputs are

schema/lockfile-v0.0.3.json

@@ -38,7 +38,7 @@
       "required": ["ref", "commit", "owner_id", "repo_id"],
       "properties": {
         "hostname": {
-          "description": "The optional bare canonical hostname of the GitHub instance that owns and resolves this dependency. The value must be github.com or a lowercase GHE tenant hostname such as octocorp.ghe.com; schemes, ports, paths, query strings, fragments, and surrounding whitespace are not allowed.",
+          "description": "The GitHub instance that owns and resolves this dependency. Omitted means the home host: the tenant on a GHE.com data-residency instance, or github.com on github.com. Producers omit it for home-host pins and write github.com only for github.com-bound pins on a GHE.com data-residency instance. When present, the value must be github.com or a lowercase GHE tenant hostname such as octocorp.ghe.com; schemes, ports, paths, query strings, fragments, and surrounding whitespace are not allowed.",
           "type": "string",
           "minLength": 1,
           "pattern": "^(github\\.com|[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.ghe\\.com)$"